Title: Troubleshooting Description: Diagnose startup, database, media, provider, publishing, and delivery problems on a self-hosted OpenPost instance. Canonical: https://docs.openpo.st/operations/troubleshooting Source: [https://docs.openpo.st/operations/troubleshooting](https://docs.openpo.st/operations/troubleshooting) # Troubleshooting Diagnose startup, database, media, provider, publishing, and delivery problems on a self-hosted OpenPost instance. ## App does not start Symptoms: container exits or the binary returns immediately. Likely cause: bad env file, missing write permissions, or invalid path settings. How to check: inspect logs and confirm `OPENPOST_DATABASE_PATH` and `OPENPOST_MEDIA_PATH`. How to fix: correct the env vars and ensure the process can write to the target directories. ## Cannot connect a social account Symptoms: auth flow starts but does not complete. Likely cause: callback mismatch, missing app keys, or missing social network access. How to check: compare the callback URL with the social network's developer page and inspect server logs. How to fix: correct the callback, app keys, and requested access. Provider-specific checks: see [Provider Troubleshooting](https://docs.openpo.st/providers/troubleshooting). ## OAuth callback mismatch Symptoms: the social network rejects the redirect or returns an invalid redirect error. Likely cause: your public URL or callback path does not match exactly. How to check: verify `OPENPOST_APP_URL`, social network callback settings, and any callback environment variables. How to fix: set the exact public callback URL and restart OpenPost. ## CORS errors Symptoms: browser console shows blocked API requests. Likely cause: incorrect `OPENPOST_APP_URL` or missing `OPENPOST_EXTRA_CORS_ORIGINS`. How to check: inspect browser dev tools and confirm the origin OpenPost is serving. How to fix: update the origin settings and restart the backend. ## Media uploads fail Symptoms: an upload fails before scheduling or a social network rejects the media. Likely cause: file too large, unsupported type, or unwritable media path. How to check: inspect upload responses and verify filesystem permissions. How to fix: correct permissions or reduce media size. ## A social network cannot fetch media Symptoms: text posts work, but media posts to Threads, Facebook, Instagram, or TikTok fail. Likely cause: `OPENPOST_MEDIA_URL` is not public. How to check: try opening a media URL from outside your local network. How to fix: expose OpenPost through HTTPS and set a public media URL. ## Scheduled post did not publish Symptoms: post remains queued or failed. Likely cause: a saved job failed, the social network is down, or the account token is no longer valid. How to check: inspect logs and Activity around the scheduled time, then check the account connection. How to fix: fix the social network or account problem, then retry the failed account. ## Database path is wrong Symptoms: empty app state after restart or startup errors. Likely cause: the database is in the wrong path or in storage that is lost with the container. How to check: confirm the actual file path mounted into the container or host. How to fix: move to a persistent path and update `OPENPOST_DATABASE_PATH`. ## Database locked Symptoms: intermittent write failures or queue delays. Likely cause: filesystem issues or too many competing processes touching the same SQLite file. How to check: confirm there is only one primary OpenPost process using the database. How to fix: keep SQLite on local durable storage and avoid multiple writers. ## Reverse proxy redirects incorrectly Symptoms: auth callbacks or login flows bounce to the wrong host. Likely cause: the proxy host name and OpenPost URL do not match. How to check: compare browser URL, proxy config, and `OPENPOST_APP_URL`. How to fix: use the same public host name and restart OpenPost. ## Wrong public URL Symptoms: pages work locally, but social network callbacks or shared media links fail. Likely cause: localhost or internal hostnames leaked into public-facing settings. How to check: inspect `OPENPOST_APP_URL`, `OPENPOST_MEDIA_URL`, and social network callback entries. How to fix: replace internal URLs with the real public HTTPS domain. ## No instance administrator Symptoms: nobody can open instance settings, configure provider applications, or manage users. Settings > Instance is hidden for every account. Likely cause: the first account was created before OpenPost promoted the first registrant to instance administrator automatically, or the database was restored from a volume where a non-admin account came first. How to check: sign in and confirm that no account shows the instance administration views under Settings. How to fix: promote an existing account from the host that runs OpenPost: ```sh docker compose exec openpost ./openpost grant-admin --email you@example.test ``` Or with a single binary: ```sh openpost grant-admin --email you@example.test ``` The command prints the promoted account and the resulting administrator count. If it reports that no account exists for that address, check the exact email under the sign-in page's registered accounts or run it again with the address each person signs in with.