Skip to content

Troubleshooting

Targeted diagnostics for the issues that come up most often. For deeper background, follow the cross-links into core concepts.

  • Platform authentication

    Emby/Jellyfin/Lidarr connection failures, 401/403 errors, refresh issues, image fetcher conflicts.

    Read more

Quick checks

A few things to try before deeper diagnostics:

  1. Read the event banner. Most operations surface their result there. A scan that "completed" with zero new artists is a different problem from a scan that errored.
  2. Check the Logs tab. Recent errors are visible without leaving the UI. Filter by level (warn / error) to skip the chatter.
  3. Look at conflict-gated chips. Amber chips in Settings > Rules indicate the conflict gate is blocking writes for that category. Resolve the underlying conflict first.
  4. Verify the connection cards. Settings > Connections shows live status for Emby / Jellyfin / Lidarr. A red status means the connection itself is failing -- fix that before suspecting Stillwater of misbehaving downstream.

Installation

Install-time issues by platform.

Native binary

  • failed to open database: unable to open database file. Stillwater is trying to write to a directory that doesn't exist or isn't writable. Check SW_DB_PATH points at a directory you can write to.
  • Web UI loads but writes to NFO files fail. The user running Stillwater (your shell user, or the systemd User=) doesn't have write access to the music directory. Confirm with ls -ln <music dir> and sudo -u stillwater touch <music dir>/.write-test.
  • Port 1973 already in use. Set SW_PORT=<something else> in the environment.

Docker / Compose

  • Container exits immediately. Check docker compose logs stillwater for the cause. The most common ones are a music-volume bind mount that points at a non-existent host path, or a database migration error if you're rolling back to an older image.
  • Web UI loads but writes to NFO files fail. PUID/PGID don't match the host user owning the music directory. Run ls -ln /path/to/your/music and confirm the numeric owner matches the PUID/PGID in your compose file.
  • Port 1973 is already in use. Another service is bound to it. Change the host-side mapping (left of the colon in ports:) to a free port.

Unraid

  • Can't find Stillwater in Community Applications. Make sure the Community Applications plugin is up to date. Stillwater appears under search; if it doesn't, refresh the CA database from the Apps tab settings.
  • WebUI shows but writes to NFO files fail. The container can't write to your music share. Confirm the music library bind mount in the template points at a real path and that PUID/PGID 99/100 (or whatever you set) has write access to that share.
  • Container starts then immediately stops. Check the container's logs from the Docker tab. The most common cause is a misconfigured volume or port conflict.

First-run wizard

  • Setup screen redirects me to login instead. Stillwater already has at least one user. The setup screen only appears when the user table is empty. If you're trying to recover a forgotten admin account, run stillwater reset-credentials (binary install) or docker compose exec stillwater stillwater reset-credentials (Docker).
  • "Path does not exist or is not writable" on a library. The directory either doesn't exist at the path you typed (typo, wrong host vs container path) or the user Stillwater runs as can't write to it. For Docker installs, check that the bind-mount in your compose file maps the host directory correctly. For binary installs, check id of the running user against ls -ln <path>.
  • The conflict pre-flight step keeps failing. Stillwater can't reach your media server. Verify the connection URL works from a curl on the Stillwater host, and that the API key is still valid.

Connections

For auth failures, conflict-gated writes, and most connection-side issues, see the dedicated Platform authentication page. The follow-ups below cover items not on that page.

  • Connection saves but library import comes back empty. The administrator user Stillwater resolved doesn't have access to the music library. In Emby or Jellyfin, open Library access for the admin user and confirm the music library is included.
  • Stillwater wrote my NFO and the platform overwrote it on next refresh. Enable the Let Stillwater manage artwork and NFO files on this server toggle on the connection. Without it, Stillwater and the platform's writer compete; with it, Stillwater is sole writer.
  • A rule is enabled in Settings but not running. Two common causes: (1) the conflict gate is closed (see the Connections-page banner). Image and NFO auto-fixes are skipped while the gate is closed. (2) The rule is filesystem-dependent and there's no local library configured; Stillwater auto-disables the "NFO exists" rule in that case. Re-add a local library or clear the conflict to resume.
  • Connection shows "Connected" but Last checked is stale. The timestamp updates when you click Test on a connection (or during initial setup); Stillwater does not run a background re-check loop. To refresh it, open Settings > Connections and trigger Test on the row.

Reporting a bug

When something is genuinely broken, file an issue on the GitHub issue tracker with:

  • Stillwater version (Settings > Updates).
  • How you installed (Docker Compose, binary, Unraid).
  • Relevant log excerpts (Settings > Logs > Download).
  • Steps to reproduce.