Troubleshooting

The application will not open

Check container status, the published port, reverse-proxy/tunnel routing, DNS, and the exact APP_BASE_URL.

View logs

docker compose logs app --tail 120
docker compose logs db --tail 80

Remove secrets before sharing any output.

Database error

Confirm PostgreSQL is healthy, credentials match the runtime configuration, the data volume is present, and you did not attempt an unsupported major-version upgrade.

Cannot sign in

Check initial setup, the public URL, HTTPS, secure-cookie settings, reverse-proxy headers, and TRUST_PROXY_LEVEL.

A screen is blank

Refresh in a current browser, inspect application logs, and check whether the view depends on a paused or unavailable integration.

A service cannot connect

Validate that the service works on its own, its internal URL is reachable from Docker, its credentials are valid, and its PlexSub diagnostic succeeds.

Reverse-proxy issues

For redirect loops or mixed content, check APP_BASE_URL, HTTPS enforcement, forwarded headers, and secure cookies.

Issues after an update

Check release notes, logs, image versions, scheduled jobs, and database migration compatibility. Restore from a tested backup if necessary.

Data loss

Stop making destructive changes. Preserve the current state, identify the affected volume or backup, and restore only through a documented, tested procedure.

What to prepare when requesting help

Provide the PlexSub version, safe/reduced logs, the affected integration, steps to reproduce, expected and actual behaviour, browser/device, and whether the issue occurs in a test account. Never include passwords, tokens, or full .env content.