Troubleshooting
Startup fails before the UI
Section titled “Startup fails before the UI”Check container logs, /data/config.yml, file permissions, SQLite parent
directory, and master key format. Exactly one master key source must decode to 32
bytes. An unsupported legacy database/schema is intentionally rejected.
invalid_client during OAuth
Section titled “invalid_client during OAuth”For custom mode, verify client ID, secret, registered callback, and Public Base URL character-for-character. Remove leading/trailing whitespace. For hosted mode, verify gateway reachability and that the selected provider is configured there.
Callback is invalid or remains pending
Section titled “Callback is invalid or remains pending”Do not reuse an old callback tab. Start Connect again and complete that session. Check reverse-proxy Host and scheme headers, browser clock, Public Base URL, and gateway/provider logs without copying query strings into an issue.
Target is connected but unreachable
Section titled “Target is connected but unreachable”Confirm connected identity, run Account test, inspect HTTP telemetry, and check provider status/rate limits. Reconnect only after distinguishing token rejection from DNS, TLS, timeout, or provider outage.
HTTP 429
Section titled “HTTP 429”Keep provider pacing and wait for Retry-After. Repeatedly pressing Test or
starting overlapping runs makes throttling worse. Same-provider targets already
share a serial batch lane.
Mapping is missing
Section titled “Mapping is missing”Expand mapping details and inspect source descriptors. Refresh AniBridge for anime, search the selected target, and create a manual override. Verify media type and season before saving. A generic movie absent from AniBridge should use a direct ID or provider search.
Plex webhook does not create a run
Section titled “Plex webhook does not create a run”Verify the URL/API key, source webhook switch, profile webhook switch, source ID, machine identifier, selected library, event type, and recent source/profile webhook events. API-key regeneration requires updating the URL in Plex.
Jellyfin webhook does not create a run
Section titled “Jellyfin webhook does not create a run”Use the official Webhook Plugin with a Generic Destination. Select User Data
Saved and Playback Stop, restrict it to the source’s configured user, set
Content-Type: application/json, and copy both the URL and JSON template from
the Jellyfin source editor. Verify the saved server/user IDs and inspect source
webhook events for an ignored event or library mismatch.
Emby webhook does not create a run
Section titled “Emby webhook does not create a run”Verify that Emby Webhooks are available for the server license and that the source URL includes the current Brokerr API key when required. Enable playback stop/scrobble, mark played/unplayed, and rating events for the configured user. Then verify the saved server/user IDs and inspect the Emby source webhook events for an ignored event or library mismatch.
SQLite is locked or unwritable
Section titled “SQLite is locked or unwritable”Run one Brokerr process against the database. Verify bind-mount ownership and write permission for the container user. Do not place active SQLite files on an unsafe network filesystem or copy them while the process is writing.
Settings revert or report a conflict
Section titled “Settings revert or report a conflict”A background reload must not overwrite dirty drafts. If another tab saved a new revision, keep the newer server state, reload, and reapply the intended edit.