Troubleshooting

Connection Issues

Timeout Error: "Connect Timeout"

Verify server URL is correct in config

vim ~/.config/jelly/config

Check Jellyfin server is running and accessible:

curl http://your-jellyfin-server:8096

Ensure port is not blocked by firewall.

Error: Config Missing 'server' or 'api_key'

Run jelly again to regenerate config

Edit ~/.config/jelly/config and add missing values

Get API key from Jellyfin Dashboard → Settings → API Keys

Installation & Dependencies

Error: Command Not Found

Verify installation:

which jelly

For AUR: yay -S jelly or paru -S jelly

Missing Dependency Errors

Install all dependencies:

Arch Linux:

sudo pacman -S chafa curl fzf jq mpv socat

Debian/Ubuntu:

sudo apt install chafa curl fzf jq mpv socat

Fedora:

sudo dnf install chafa curl fzf jq mpv socat

macOS:

brew install chafa curl fzf jq mpv socat

Media Preview Issues

Cover Images Not Showing

Verify media_preview=yes in config

Check terminal supports ANSI colors/sixels (kitty recommended)

Verify chafa installed:

chafa --version

Preview Window Doesn't Resize Properly

Works best in kitty terminal

Try a different terminal emulator

Playback Issues

Player Not Found

Verify player installed:

which mpv
which iina

Correct player in config:

vim ~/.config/jelly/config

Video Won't Play / Buffering Issues

Check internet connection

Verify Jellyfin server is responsive

Check if mpv is stuck:

ps aux | grep mpv

Resume Position Not Saving

Increase mark_continue_percentage in config (default is 5%)

Verify media_preview=yes enables tracking

Check Jellyfin user account has watch permissions

Configuration Issues

Config File Corrupted

Backup:

cp ~/.config/jelly/config ~/.config/jelly/config.bak

Delete original:

rm ~/.config/jelly/config

Run jelly again to regenerate

Restore from backup if needed:

cp ~/.config/jelly/config.bak ~/.config/jelly/config

Can't Edit Config / Editor Won't Open

Verify editor is installed:

which vim
which nano

Try different editor:

nano ~/.config/jelly/config

Performance Issues

Slow Library Loading

Large libraries take time to fetch (normal for 1000+ items)

Use Search for faster access to specific content

Kill stuck mpv processes:

killall mpv