Backend started successfully on port 3000, the backend checks its settings and logs each problem as a Configuration issue. It keeps running either way, so read those lines first.
Start-up
The container restarts in a loop, or gets killed
The container restarts in a loop, or gets killed
Usually memory. The Compose stack needs about 4 GB.
docker stats shows usage, and dmesg on the host shows the kernel killing a process.On v3.6.121 the container restarts in a loop with a data loss warning
On v3.6.121 the container restarts in a loop with a data loss warning
The log shows Prisma’s data loss warning and suggests
--accept-data-loss. v3.6.121 applied the schema without that flag, which stopped installs that came from a release older than v3.6.107. Move the image to v3.6.122 or newer and recreate the container. See Backups and upgrades.The backend stops: UPLOAD_DIRECTORY is not set
The backend stops: UPLOAD_DIRECTORY is not set
The log says
STORAGE_PROVIDER is "local" but UPLOAD_DIRECTORY is not set. Local storage needs a folder. In the official image, set UPLOAD_DIRECTORY=/uploads and NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY=uploads, as the Compose file does. See Uploads and storage.The database connection is refused
The database connection is refused
Check
DATABASE_URL. Inside a container, localhost is the container itself: use the service name, postqueen-postgres in the Compose file. docker compose logs postqueen-postgres should show database system is ready to accept connections. Outside Compose, the container must be on the same Docker network as the database.A port is already in use
A port is already in use
Another program holds 4007, 7233 or 8080. Stop it, or change the left-hand number of that port in
docker-compose.yaml. If you move 4007, change the port in MAIN_URL, FRONTEND_URL and NEXT_PUBLIC_BACKEND_URL too.Building from source runs out of memory
Building from source runs out of memory
The build needs more memory than running the image. Raise Node’s limit for the build,
NODE_OPTIONS="--max-old-space-size=4096" pnpm run build, but not above the machine’s memory. On a small server, pull the published image instead of building.Sign-in
Signing in returns to the login page
Signing in returns to the login page
The browser dropped the login cookie. On HTTPS,
FRONTEND_URL must match the address in the browser exactly, with the scheme and without a trailing slash. On plain HTTP, the cookie needs NOT_SECURED=true, which is for a local try only.Origin not allowed
Origin not allowed
The backend accepts browser requests only from
FRONTEND_URL and MAIN_URL. Opening PostQueen on any other host or port is refused. Set both to the address people use.Everyone was signed out after a restart
Everyone was signed out after a restart
JWT_SECRET changed. It signs every session. If ENCRYPTION_KEY was never set, the same value also encrypted the API key and the stored credentials of networks such as Bluesky and WordPress, and those stop working too. Put the old value back: that recovers everything. Then set ENCRYPTION_KEY to that same value before you rotate JWT_SECRET. See Encryption keys.Continue with Google is denied, or only some accounts get in
Continue with Google is denied, or only some accounts get in
Google sign-in uses the YouTube web client,
YOUTUBE_CLIENT_ID and YOUTUBE_CLIENT_SECRET, and its redirect URI FRONTEND_URL + /integrations/social/youtube. While the Google app is in Testing, only its listed test users can sign in: publish it, or add the person. See YouTube setup.Google consent works, then sign-in fails with invalid_client
Google consent works, then sign-in fails with invalid_client
The backend log shows
invalid_client from Google’s token endpoint: YOUTUBE_CLIENT_SECRET does not belong to that client. Add a new secret to the same web client in Google Cloud, put it in .env, and recreate the container. Google shows a secret in full only when you create it.New accounts stay inactive
New accounts stay inactive
REQUIRE_EMAIL_ACTIVATION=true with a mail provider that cannot deliver. Fix email, or remove the setting.Connecting channels
Connecting worked yesterday and fails after a domain change
Connecting worked yesterday and fails after a domain change
Every redirect URI is built from
FRONTEND_URL. Update the redirect URI in each network’s developer console to the new address.fetch failed, with Blocked IP in the log
fetch failed, with Blocked IP in the log
The server refused to call a private or local address. That protects against requests to your internal network. If the Bluesky, Lemmy, WordPress, Listmonk or Mastodon server really is on your network and everyone who can add channels is trusted, set
DISABLE_SSRF_PROTECTION=true. Otherwise fix DNS so the name resolves to a public address.fetch failed without Blocked IP
fetch failed without Blocked IP
The server cannot reach the network’s API: DNS, a firewall or blocked egress. PostQueen reads no
HTTPS_PROXY, so behind an egress proxy allow the hosts at the network layer. Self-hosting overview lists the main ones.Hide a network from Add Channel
Hide a network from Add Channel
Set
HIDDEN_PROVIDERS to the identifiers to hide, for example tiktok,x, and recreate the container. Connected channels keep working. MIGRATE_PROVIDERS moves channels to another network on their next reconnect: see Hide or move a network.Posts and background work
Posts are scheduled and never publish
Posts are scheduled and never publish
Publishing runs in the orchestrator, through Temporal. Check that the
temporal container is healthy (docker compose ps) and that TEMPORAL_ADDRESS points at it. Both the backend and the orchestrator must reach it. Running from source, pnpm run dev-backend starts no orchestrator: use pnpm run dev.Posts that failed to schedule are never picked up
Posts that failed to schedule are never picked up
RUN_CRON is not set, so the recurring recovery workflow never started. Set RUN_CRON=true on one backend. The Helm chart does not set it.A post failed
A post failed
Open the post in the calendar: the error the network returned is on the post. See A post did not go out.
Uploads and email
Uploaded images do not show
Uploaded images do not show
With local storage in the official image,
UPLOAD_DIRECTORY must be /uploads and NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY must be uploads. After a domain change, old files keep the old address until you set PREVIOUS_FRONTEND_URLS. See Uploads and storage.Posts with media fail on Instagram, Facebook or Threads
Posts with media fail on Instagram, Facebook or Threads
Those networks download the file from its address. On a laptop or a private network the address is not reachable from the internet. Use a public HTTPS domain or Cloudflare R2.
413 Request Entity Too Large
413 Request Entity Too Large
Your reverse proxy limits the body size. Allow 1 GB:
client_max_body_size 1G; in Nginx. See Nginx.No email arrives
No email arrives
EMAIL_PROVIDER must be exactly resend or nodemailer, with EMAIL_FROM_ADDRESS and EMAIL_FROM_NAME set. Without them nothing is sent and nothing fails. See Email.Platform questions
Can I run it on Vercel or another serverless host?
Can I run it on Vercel or another serverless host?
Not the backend or the orchestrator. The backend is a long-running server, and the orchestrator is a Temporal worker that runs all the time. Run them on a virtual machine, a container host or Kubernetes. The official image already runs nginx, the frontend, the backend and the orchestrator together.
Can I run more than one container?
Can I run more than one container?
Yes, with shared PostgreSQL, Redis and Temporal. Media needs a volume every container mounts, or Cloudflare R2. Set
RUN_CRON on one of them only.