Start with the Worker's logs. Open your Worker in the Cloudflare dashboard and choose Logs, or stream them while you reproduce the problem:
npx wrangler tail -c wrangler.selfhost.jsonc
I signed in but I'm not an admin
The first-admin rule only promotes someone when all of these are true:
- the address you signed in with is listed in
ADMIN_EMAILS(case and spaces don't matter); - it is verified: you used an email sign-in link, or GitHub or Discord reported it as verified;
- nobody is superadmin yet.
Check the vars block of wrangler.selfhost.jsonc and deploy again if you changed it, then sign out and back in. The check runs at every sign-in until a superadmin exists.
"No sign-in providers are set up yet"
Neither email nor a login provider is set up. Set the SMTP secrets or a GitHub or Discord OAuth app as in Install, step 6.
Sign-in fails or loops back to the sign-in page
BETTER_AUTH_URLmust match the address in your browser exactly:https, the same host, no trailing slash.- For GitHub or Discord, the OAuth app's callback URL must be
https://your-app-host/api/auth/callback/github(or/discord). - Changing
BETTER_AUTH_SECRETsigns everyone out. That is expected.
Emails don't arrive
Send a test from Admin → Emails; its log shows the error. Workers can't connect on port 25, so use 587 with STARTTLS or 465 with TLS. Some providers also need the from address to be one they have verified.
"Worker exceeded resource limits" (error 1102)
The account is on the Workers Free plan, which allows 10 ms of CPU per request. planpage needs Workers Paid, and the limits block in the template raises the limit to 30 seconds.
System settings can't be saved or decrypted
SETTINGS_KEY is missing, or has changed since the settings were saved. Put back the original key. If it's lost, set a new one and enter the settings again; anything encrypted with the old key, including saved sign-in tokens, can't be recovered, and people may need to sign in with GitHub or Discord again.
Diagrams show as code on share pages
The browser binding is missing from your config, or your account has used its included browser time. Diagrams still render inside the app.
An agent can't connect
- Use your own server's address:
https://your-app-host/mcp. - The agent signs in through a browser window on your app host. If that window shows an error, check the Worker logs for the request.
- Agent sign-in keeps its state in KV, so the
OAUTH_KVbinding must point at a namespace that exists.
A migration fails
Run pnpm selfhost:migrate again and read the error. Migrations that already ran are skipped, so it is safe to retry. If one keeps failing, open an issue on GitHub with the output.
The deploy stops with "couldn't read the database registry"
pnpm selfhost:deploy reads the list of databases from your D1 database before it deploys, so the Worker is bound to every one of them. It stops if it can't:
- Run
pnpm selfhost:migratefirst. A new install, or an update from before the list existed, doesn't have it yet. - Check that
npx wrangler whoamishows the account your database is in, and that the database id inwrangler.selfhost.jsoncis right.
Don't work around it with a bare wrangler deploy. In scaled mode that deploys a Worker that can't reach the documents in the other databases.
Still stuck
Search or open an issue on GitHub. Include the version (git rev-parse --short HEAD), what you did and the relevant lines from wrangler tail. Leave out secrets and your users' data.