# Troubleshooting

> Fixes for the problems people hit most when self-hosting planpage.

Start with the Worker's logs. Open your Worker in the Cloudflare dashboard and choose **Logs**, or stream them while you reproduce the problem:

```sh
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](https://planpa.ge/docs/self-host-install.md), step 6.

## Sign-in fails or loops back to the sign-in page

- `BETTER_AUTH_URL` must 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_SECRET` signs 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_KV` binding 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](https://github.com/Bifrostdotgg/planpage/issues) 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:migrate` first. A new install, or an update from before the list existed, doesn't have it yet.
- Check that `npx wrangler whoami` shows the account your database is in, and that the database id in `wrangler.selfhost.jsonc` is right.

Don't work around it with a bare `wrangler deploy`. In [scaled mode](https://planpa.ge/docs/self-host-scaling.md) that deploys a Worker that can't reach the documents in the other databases.

## Still stuck

Search or open an issue on [GitHub](https://github.com/Bifrostdotgg/planpage/issues). 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.
