Common issues and solutions for TTYverse. If you don't find your issue here, check the FAQ or report it at https://git.stormux.org/storm/ttyverse/issues.

Connection Issues

"Connection failed" or "Cannot connect to server"

Symptoms:

-- ERROR: Connection failed
-- Unable to fetch timeline

Solutions:

Check internet connection:

ping 8.8.8.8
curl -I https://google.com

Verify server URL:

# Check your configured server
grep apibase ~/.config/ttyverse/ttyverse_rc

# Test server manually
curl https://your-instance.com/api/v1/instance

Check server status:
- Visit your server's web interface
- Check server status pages
- Try different DNS servers

Firewall/proxy issues:

# Test if curl works
curl https://your-instance.com/api/v1/instance

# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

SSL/TLS Certificate Issues

Symptoms:

-- SSL certificate problem
-- unable to get local issuer certificate

Solutions:

Update CA certificates:

# Debian/Ubuntu
sudo apt update && sudo apt install ca-certificates

# Arch Linux
sudo pacman -S ca-certificates

Check system time:
```
date
# Ensure system time is correct
```

Test SSL manually:

openssl s_client -connect your-instance.com:443 -servername your-instance.com

Authentication Issues

"Unauthorized" or "Token not supplied"

Symptoms:

-- ERROR: Unauthorized: token not supplied
-- Authentication failed

Solutions:

Check OAuth credentials:

# Verify token exists
cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey

# Check file permissions
ls -la ~/.config/ttyverse/

Re-authenticate:

# Remove old credentials
rm ~/.config/ttyverse/oauth_credentials
rm ~/.config/ttyverse/ttyverse_rc

# Restart TTYverse for fresh setup
./ttyverse.pl

Check token validity:

# Test token manually
TOKEN=$(grep tokenkey ~/.config/ttyverse/ttyverse_rc | cut -d= -f2)
curl -H "Authorization: Bearer $TOKEN" https://your-instance.com/api/v1/accounts/verify_credentials

OAuth Setup Fails

Symptoms:

Browser doesn't open during setup
"Failed to get authorization code"
OAuth redirect fails

Solutions:

Manual OAuth setup:
- Copy the authorization URL from TTYverse
- Open in browser manually
- Copy authorization code back to TTYverse

Check browser setup:

# Test browser detection
echo $DISPLAY
which xdg-open firefox chrome

Alternative authentication:
- Use different device for OAuth
- Try text-based browser
- Check server's OAuth settings

Performance Issues

Slow Timeline Loading

Symptoms:

Long delays fetching posts
Timeouts during refresh

Solutions:

Adjust refresh settings:

# Increase refresh interval
/set effpause 300

# Reduce post count
/set timeline_count 15

Check network speed:

# Test connection speed to server
time curl -I https://your-instance.com/

Server performance:
- Try different instance
- Check server status
- Use smaller media uploads

High Memory Usage

Symptoms:

TTYverse consuming excessive RAM
System becoming unresponsive

Solutions:

Reduce cache size:

# Edit config to reduce cached posts
echo "timeline_cache=50" >> ~/.config/ttyverse/ttyverse_rc

Restart periodically:

# Exit and restart TTYverse
/quit
./ttyverse.pl

Monitor memory:

# Check TTYverse memory usage
ps aux | grep ttyverse
top -p $(pgrep ttyverse)

Media Upload Issues

Media Upload Fails

Symptoms:

-- ERROR: Media upload failed
-- Response: {"error":"File too large"}

Solutions:

Check file size:

# Check file size
ls -lh /path/to/file

# Common limits:
# Images: 8MB on Mastodon
# Video/Audio: 40MB on Mastodon

Verify file format:

# Check MIME type
file --mime-type /path/to/file

# Supported: image/*, audio/*, video/*

Test with smaller file:

# Create test image
convert -size 100x100 xc:red test.jpg
/media test.jpg

Alt-text Issues

Symptoms:

Upload cancelled for images
Alt-text prompt not appearing

Solutions:

Provide alt-text:
- Always describe images meaningfully
- Don't leave alt-text empty
- Use descriptive, concise language

Check file type detection:

# Verify file is detected as image
file --mime-type /path/to/image.jpg
# Should show: image/jpeg

Sound and Extension Issues

No Sound Notifications

Symptoms:

Sound notifications not playing
Silent operation

Solutions:

Check sound files:

# Verify sound files exist
ls ~/.local/share/ttyverse/sounds/default/

# Test sound playback
paplay ~/.local/share/ttyverse/sounds/default/default.ogg

Check audio system:

# Test system audio
speaker-test -c 2 -t wav

# Check PulseAudio
pulseaudio --check

Install sound dependencies:

# Install PulseAudio utils
sudo apt install pulseaudio-utils    # Debian/Ubuntu
sudo pacman -S pulseaudio           # Arch Linux

Extension Loading Fails

Symptoms:

** ERROR: Failed to load extension soundpack.pl

Solutions:

Check extension files:

# Verify extensions exist
ls ~/.local/share/ttyverse/extensions/

# Check file permissions
chmod +x ~/.local/share/ttyverse/extensions/*.pl

Install Perl dependencies:

# Common Perl modules needed
cpan Audio::Play::Simple
cpan Desktop::Notify

Manual extension loading:

# Test extension manually
perl ~/.local/share/ttyverse/extensions/soundpack.pl

Display and Terminal Issues

Readline Problems

Symptoms:

No command history
No tab completion
Broken line editing

Solutions:

Install Perl readline:

# Install Term::ReadLine::Gnu
sudo apt install libterm-readline-gnu-perl    # Debian/Ubuntu
cpan Term::ReadLine::Gnu                      # Manual install

Check terminal compatibility:

# Verify terminal type
echo $TERM

# Test readline
perl -MArray::ReadLine::Gnu -e 'print "Readline available\n"'

Alternative terminals:
- Try different terminal emulator
- Use screen or tmux
- Check terminal settings

Character Encoding Issues

Symptoms:

Garbled text
Unicode characters display incorrectly
Emoji problems

Solutions:

Check locale settings:

# Verify UTF-8 locale
locale
echo $LANG

# Set UTF-8 if needed
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Terminal encoding:
- Ensure terminal supports UTF-8
- Check terminal preferences
- Try different terminal emulator

Configuration Issues

Config File Not Found

Symptoms:

-- Config file not found
-- Using defaults

Solutions:

Create config directory:

mkdir -p ~/.config/ttyverse/
chmod 700 ~/.config/ttyverse/

Check XDG variables:
```
echo $XDG_CONFIG_HOME
echo $HOME
```

Manual config creation:

# Create basic config
cat > ~/.config/ttyverse/ttyverse_rc << EOF
effpause=120
verbose=1
readline=1
EOF

Permission Denied Errors

Symptoms:

-- ERROR: Permission denied writing to config

Solutions:

Fix permissions:

# Set correct permissions
chmod 700 ~/.config/ttyverse/
chmod 600 ~/.config/ttyverse/*

Check ownership:

# Verify you own the files
ls -la ~/.config/ttyverse/

# Fix ownership if needed
chown -R $USER:$USER ~/.config/ttyverse/

Getting Debug Information

Enable Debug Output

# Run with verbose output
./ttyverse.pl -verbose

# Enable debug in session
/debug
/verbose

Collect System Information

# System info
uname -a
perl --version
curl --version

# TTYverse info
./ttyverse.pl -version

# Config info
ls -la ~/.config/ttyverse/
cat ~/.config/ttyverse/ttyverse_rc | grep -v tokenkey

Log Analysis

# Check for error patterns
grep -i error debug.log
grep -i failed debug.log
grep -i timeout debug.log

# Timeline of events
tail -f debug.log

Reporting Issues

When reporting bugs, include:

TTYverse version: ./ttyverse.pl -version
System info: uname -a and perl --version
Error messages: Copy exact error text
Steps to reproduce: What you were doing when it failed
Debug output: Run with -verbose and include relevant logs
Configuration: Sanitized config (remove tokens!)

Report at: https://git.stormux.org/storm/ttyverse/issues

See also: FAQ | Configuration | Getting Started

Last updated: 2025-07-28