Troubleshooting

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.

Shared Library Paths Across Platforms

If Emby and Jellyfin (or Lidarr) are configured to manage the same music directory, their background processes can interfere with each other and with Stillwater. This is the most common source of "mysterious" metadata and image changes.

What happens

Media servers do not just read your music folder -- they also write to it. When you enable settings like "Save artwork into media folders" or "Save metadata to NFO files," each server writes its own copies of images and NFO files directly into your artist directories. If two servers share the same directory, one server's writes trigger the other server's file watcher, which may overwrite or delete what was just written.

For example:

• Stillwater saves a new artist thumbnail to the folder
• Emby's file watcher detects the new image and schedules a metadata refresh
• During the refresh, Emby replaces the image with its own cached version (or a lower-quality copy from an online provider)
• The original image Stillwater saved is gone

The same applies to NFO files. One server writes an NFO, the other detects the change and overwrites it with its own version, which triggers the first server again -- creating an update loop that can run until both servers settle on the last writer's data.

How to avoid it

The safest configuration is to give each media server its own library entry that points to a unique directory, or to disable metadata/image saving on all but one server:

Option A: Separate directories (recommended)

Mount the same music collection at different paths inside each container. Each server sees the same files but writes metadata to its own location:

Server	Mount	Container path
Stillwater	/mnt/music	/music
Emby	/mnt/music	/data/music
Jellyfin	/mnt/music	/data/music

Then configure Emby and Jellyfin to save metadata/images into server-specific folders (their default /config/metadata paths) rather than into the media folders.

Option B: Single writer

If all servers must share exactly the same path, designate one server as the writer and disable metadata saving on the others:

• Emby: Dashboard > Library > uncheck "Save artwork into media folders"
• Jellyfin: Dashboard > Libraries > (library) > uncheck "Save artwork into media folders" and uncheck metadata savers under Advanced
• Lidarr: Settings > Media Management > uncheck "Rename Tracks" and "Import Extra Files" if they include NFO

Stillwater can push metadata and images to each server via API without relying on the filesystem, so the servers do not need write access to the shared directory.

Option C: Accept the trade-off

If you understand the risks and prefer convenience over isolation, you can leave the shared path in place. Stillwater's NFO conflict detection will warn you when an external process modifies a file it manages, and you can choose which version to keep. However, image overwrites are not detected and will happen silently.

Symptoms of a shared-path conflict

• Images reverting to lower quality or different versions after saving
• NFO conflict warnings appearing shortly after saving metadata
• Metadata changes not "sticking" -- values revert within minutes
• Stillwater logs showing repeated write-back attempts

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.