Troubleshooting
Startup fails before the UI
Section titled “Startup fails before the UI”Check logs, /data/config.yml, data-directory ownership, database parent, and
master key. Exactly one key source must decode to 32 bytes. Do not run a second
Brokerr process against the same database.
SQLite is locked or unwritable
Section titled “SQLite is locked or unwritable”Verify the container user owns the persistent tree and the filesystem supports SQLite locking. Brokerr configures WAL, NORMAL synchronous mode, and a ten-second busy timeout automatically. Do not copy/delete active WAL/SHM files.
Hosted authorization remains pending
Section titled “Hosted authorization remains pending”Start a new connection rather than reusing an expired browser tab. A session lasts 10 minutes and a ready bundle waits 5 minutes. Verify gateway health, browser clock, HTTPS, and outbound network access.
Custom OAuth reports invalid_client
Section titled “Custom OAuth reports invalid_client”Verify client ID/secret and the exact redirect URI shown after selecting custom mode. Remove whitespace and do not register hosted gateway callbacks for a custom app.
Target is connected but the test fails
Section titled “Target is connected but the test fails”Use the API tester and distinguish token rejection from DNS, TLS, timeout, provider outage, or rate limiting. Reconnect only for credential/refresh errors.
HTTP 429, 503, or timeout
Section titled “HTTP 429, 503, or timeout”Keep provider pacing enabled and respect Retry-After. Repeated manual tests can worsen throttling. Plex cloud history uses bounded retries/backoff; Letterboxd diary POST avoids blind retry and reconciles ambiguous results.
Mapping is missing or wrong
Section titled “Mapping is missing or wrong”Inspect identifiers and provenance. Refresh AniBridge for anime, verify season/ segment coordinates, use target search, and save a profile-scoped manual mapping. Letterboxd intentionally does not guess from title alone.
Plex webhook does not create a run
Section titled “Plex webhook does not create a run”Verify webhook URL/API key, profile webhook switch, live baseline, source ID, selected library, and event history. Events outside the profile libraries are discarded before a run; collection changes do not have reliable webhook support.
Continue Watching did not pause/drop AniList
Section titled “Continue Watching did not pause/drop AniList”The item must be started, unfinished, previously observed inside Continue Watching, and then observed outside. An initial full snapshot cannot prove a transition. Confirm Playback state is enabled and inspect the source observation.
Letterboxd diary did not receive a date
Section titled “Letterboxd diary did not receive a date”Check that Diary history is enabled, the movie is completed, and an exact event
or valid lastViewedAt exists. Bulk Watched detection may deliberately suppress
weak timestamps; the run badge/details explain this. A higher viewCount alone
does not authorize invented dates.
Managed list is partial
Section titled “Managed list is partial”Open Lists and inspect unmatched/ignored members, binding status, target version conflict, and last run. Incomplete source scans never remove members. Resolve manual mappings and run a full dry reconciliation before retrying a mirror.
Settings report a conflict
Section titled “Settings report a conflict”Another tab saved a newer row revision. Reload the newer server state and reapply the intended edit rather than overwriting it.