Skip to content

Troubleshooting

Jump to bottom
Jesse Slaton edited this page Feb 26, 2026 · 2 revisions

Troubleshooting

Checking Logs

View container logs:

docker logs stillwater

Follow logs in real time:

docker logs -f stillwater

For more verbose output, set the log level to debug:

environment:
  - SW_LOG_LEVEL=debug

Common Issues

Permission denied writing NFO or image files

Stillwater writes files to your music library directories. The container process must have write access.

  • Ensure PUID and PGID match the owner of your music files
  • Check permissions: ls -la /path/to/music/SomeArtist/
  • The container runs as the user specified by PUID/PGID via su-exec

Database is locked

SQLite supports only one writer at a time. If you see "database is locked" errors:

  • Ensure only one Stillwater instance is running against the same database file
  • Check that no other process (backup tool, file sync) is holding a lock on the .db file
  • WAL mode is enabled by default, which allows concurrent reads during writes

Scanner finds no artists

  • Verify the music directory is mounted correctly: docker exec stillwater ls /music
  • Check that the library path in Settings matches the container mount point
  • Artist directories must be top-level folders inside the library path
  • Directories matching the exclusion list (Various Artists, VA, Soundtrack, OST) are skipped by default

Provider API key errors

  • API keys are encrypted at rest. If the encryption key changes (e.g., recreating the data volume), existing keys become unreadable and must be re-entered
  • Use the "Test" button in Settings to verify each provider key
  • MusicBrainz does not require an API key but is rate-limited to 1 request per second

Connection test fails for Emby/Jellyfin/Lidarr

  • Verify the server URL is reachable from inside the container: docker exec stillwater wget -qO- http://your-server:8096/System/Info/Public
  • Use the container's network perspective (e.g., http://host.docker.internal:8096 if running on the same host)
  • Check that the API key has sufficient permissions

Images not showing in media server after save

  • Trigger a library refresh from the artist detail page (or use the push feature)
  • Confirm the image filenames match your platform profile expectations (see the in-app guide at /guide#platform-profiles)
  • Some media servers cache images aggressively; a full library scan may be needed

NFO conflict warning

Stillwater checks the last-modified timestamp of existing NFO files before overwriting. If another tool (Kodi, Lidarr, manual edit) modified the file since Stillwater last wrote it, a warning is shown. You can choose to overwrite or keep the external version.

Reset Admin Credentials

If you are locked out, use the reset command:

docker exec stillwater stillwater reset-credentials

This resets the admin account so you can log in and set a new password.

Getting Help

If your issue is not covered here, open an issue on GitHub.

Clone this wiki locally