scootbg troubleshooting

Symptoms

set says no such file / not an image / too large. The file must exist, be a regular file, and start as PNG, JPEG or WebP (told apart by content, not name); images over 16384×16384 pixels are refused. Every output keeps what it showed.
A link won’t show. In order: no curl on PATH; host unresolvable (names curl’s exit); HTTP error (exited 22); error page (“do not start as a PNG, JPEG or WebP”, caches nothing); past 32 MiB (link something smaller); sha256 mismatch (prints both hashes — copy the actual one in, or drop the pin); unwritable cache dir. Offline at startup, the background shows until the next set, apply-config, reconfigure, or restart with the network back. Full detail in Wallpaper from a link.
Image not filling the screen. Check --mode: fill covers and crops (the default), fit letterboxes with --fill, stretch distorts, center draws unscaled, tile repeats. A 20,000,000×1 strip with fit/stretch is a drawing error — fill, center or tile show it.
Wrong output / unknown output. set --output NAME names a connector query lists; a name no output has right now is an error (exit 1) changing nothing. set with no --output replaces every choice, per-output ones included.
Restore lost it. query reports "saving":false while saving is off (unreadable state file, or a newer version’s format — stderr names which file to remove or fix). A saved image that moved is skipped with a warning until the file is back; a saved link re-downloads instead. See Restore.
A second daemon / stale socket. One daemon per display; a second scootbg daemon refuses while one runs, and a socket left by a dead one is replaced. Signals leave the socket file; the next daemon replaces it.
Nothing applied from scoot. Check the [wallpaper] section (The [wallpaper] section): an unknown key or wrong-typed value refuses the section (the rest of the file still applies); command naming nothing warns and retries next reload. And leave scootbg daemon out of [autostart] — apply-config starts it.

Diagnose with query

scootbg query

draw_failed: true tells a failed draw apart from a clear; draw_error says why; shows names what’s on screen (with url beside image for a download); saving and profile name the state behind Restore. Exit statuses: 0 done; 1 no daemon, unknown output, unshowable image, or drawing failed; 2 usage error.