Troubleshooting

Each entry lists the symptom, likely causes, a diagnostic step and a fix.

The server prints “Use —start flag” and exits

Cause: the server requires the --start flag to run.

Fix: start it with wallpaper-server --start. See installation.

”Configuration file not found”

Symptom: the server exits reporting a missing config file.

Causes: no config at the resolved path.

Diagnose: the path is chosen as --config flag → $WALLPAPER_SERVER_CONFIG → ~/.config/wallpaper-server/config.yaml.

Fix: create a config at that path, or point to one explicitly:

wallpaper-server --start --config /path/to/config.yaml

See configuration.

”no wallpaper folders specified in configuration”

Cause: wallpaper_folders is empty. It is required.

Fix: add at least one directory under wallpaper_folders and restart.

No wallpapers found

Symptom: the gallery is empty and GET /api/wallpapers returns an empty list.

Causes: the folders contain no supported files, or they have not been scanned yet.

Diagnose:

curl "http://localhost:8519/api/wallpapers?limit=1"

Fix: confirm the folders contain .jpg, .jpeg, .png or .webp files, then trigger a rescan:

curl -X POST "http://localhost:8519/api/refresh"

Filters return no results

Cause: filters combine with AND, so an over-constrained query can match nothing. On the direct-image endpoint this returns 404.

Fix: loosen or remove filters and check what your library actually contains. See the filter reference.

Port already in use

Cause: another process is bound to the configured port (default 8519).

Fix: stop the other process, or change server.port in the config.

Works locally but not from another device

Causes: the server is only reachable on the host, or a firewall blocks it.

Diagnose: from the other device, curl "http://SERVER-IP:8519/api/wallpapers?limit=1".

Fix: ensure server.host is 0.0.0.0 (the default) so the server listens on all interfaces, open the port in your firewall, and use the server’s LAN address. Note there is no authentication — do not expose it directly to the public internet without a reverse proxy. See the API overview.

Docker cannot see my images

Cause: the host folders are not mounted into the container.

Fix: mount your wallpaper folder and config as volumes and point the config at the in-container paths. See installation.

Upload fails

Causes: wrong form field, unsupported extension, or a file over the 50 MB limit.

Fix: send a multipart request with the field named file and a supported format. Errors come back as plain text with a 400 status — see errors.

Cache cannot be created

Cause: the process cannot write to the cache or uploads directory.

Fix: ensure the user running the server can create and write the configured cache_dir and uploads_dir. See caching and storage.

Gallery shows stale data

Cause: files changed on disk but the index has not been rebuilt.

Fix: trigger POST /api/refresh (or restart). Note that changing folders via PUT /api/settings also requires a refresh or restart to take effect.

A page or API path returns 404

Causes: wrong method or path, or an ID that is not in the index.

Fix: check the method and path against the endpoint reference. Remember random matching returns 404 when no wallpaper matches the filters.