# scootbg troubleshooting

"Wallpaper symptoms and their fixes — images, links, outputs, restore."

## 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](./from-url.md).
- *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](./restore.md).
- *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](./index.md#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

```sh
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](./restore.md). Exit statuses: `0` done; `1` no
daemon, unknown output, unshowable image, or drawing failed; `2`
usage error.