Troubleshooting

Start with goose doctor. Most problems are an old yt-dlp.

goose doctor

#Nothing plays, or a track fails

YouTube changes often, and an out-of-date yt-dlp is the usual culprit. Update it (yt-dlp -U, or through your package manager), then try again. If yt-dlp lives somewhere unusual, point gooseneck at it with goose config set bin_dir /path/to/dir.

#Downloads fail with 403

These are often temporary. gooseneck already retries each track three times; re-run the same goose download and it only fetches what's missing.

#No pictures

Real images need a terminal with the Kitty graphics protocol (Kitty, Ghostty). Inside tmux you get half-block art. Force a mode with GOOSENECK_IMAGES=halfblock, or press i to turn art off.

#The music won't stop

That's on purpose: the player outlives the TUI.

goose stop          # stop and clear the queue
goose quit-player   # shut it down

#Scrobbles aren't showing up

goose scrobble          # status, including queued listens
goose scrobble flush    # send them now

Remember a track only counts after half its length or 4 minutes of actual listening.

#Start fresh

goose cache clear       # drop cached pages (history is kept)
GOOSENECK_HOME=/tmp/goose-test goose    # a clean, throwaway setup

#Still stuck?

Open an issue with the output of goose doctor and goose version.