Troubleshoot Self-Hosted Workspaces

Start with the process logs and /healthz, then test a real sign-in and one write. Health proves that Workspaces started. It does not prove OIDC discovery, Cloudflare Access, free disk space, or every storage write.

Container boot and health

Result	Cause and recovery
The container exits before port `8790` opens	Read `docker logs rooms`. The log lists missing settings, secrets that are too short, an unwritable data directory, an unsupported auth mode, or another process holding the data lock.
A second container fails on the same volume	Stop the first process. Workspaces supports one process per data directory. Do not overlap old and new containers during an update.
The data directory is not writable	Use a named Docker volume or make the bind mount writable by user ID `1000`. Do not use NFS, SMB, EFS, or another shared network filesystem.
`/healthz` returns `200` but writes fail	Check free disk space and the container logs. Health does not write to SQLite or a live-edit log.
One document stops live editing after a disk error	Free disk space. Workspaces closes that document’s live session instead of sending an edit it could not save. Reopen the document after storage writes recover.

Result	Cause and recovery
Log in fails before the provider opens	Check that the HTTPS issuer is reachable and returns valid OpenID Connect discovery data. For a private CA, mount its certificate and set `NODE_EXTRA_CA_CERTS`.
The provider rejects the callback	Register the exact public app origin followed by `/auth/callback`. Confirm the client ID and optional client secret match that registration.
The browser returns to the signed-out page	Serve the app over HTTPS. Workspaces marks its sign-in cookies `Secure`. Keep `OIDC_COOKIE_SECRET` stable across restarts.
Workspaces returns `401 unauthorized` after the callback	Start a fresh login. Verify the registered callback, client ID, client secret, and that the ID token supplies `sub` and `email`. Workspaces returns a generic `401`; use the identity provider’s logs for token-exchange details. Do not reload an old callback URL.
The provider accepts only a public client	Remove `OIDC_CLIENT_SECRET` only after registering Workspaces as a public client. PKCE remains enabled.

Workspaces can start even if OIDC discovery later fails because discovery begins at the first login.

API keys

Result	Cause and recovery
You cannot create the first key	Sign in through the browser first. Key creation and management require a human session.
A key is missing from Settings > API keys	Confirm you signed in as the key owner. Do not insert keys into SQLite. A database-created key may have no owner who can list or revoke it.
A revoked key still appears to work	Stop the client and send a new request. A request already in progress may finish; new requests should return `401 unauthorized`.
Removing sign-in access leaves automation working	Removing a person’s sign-in access does not revoke their API keys. Restore sign-in so the key owner can revoke each key.

Backup, restore, and update

Result	Cause and recovery
A cold restore will not boot	Restore into a fresh volume and confirm the archive includes `.plannotator-ready`. Use the image version that created the backup or a newer one.
A hot restore fails on the lock or SQLite	Set user and group ownership of all restored files to ID `1000`. Write `.plannotator-ready` only after you copy every data directory.
Assets are missing after a hot restore	Repeat the backup and include `/data/assets` after metadata, live logs, and Git repositories.
An old container reports unknown migrations	Do not start it on the migrated volume. Restore the pre-update backup into a fresh volume and use the old image there.
A Cloudflare D1 restore fails	Apply the source migrations to a fresh D1 database, then import data-only `INSERT` statements in parent-first order. Do not replay a raw `wrangler d1 export` file as-is.
`wrangler d1 execute --file` exits `0`, but rows are missing	The command may have canceled at a confirmation prompt. Compare row counts with the backup before trusting the restore.
An older Cloudflare deployment needs a newer schema	Do not deploy old source against changed data. Restore the pre-update D1 backup and use the matching source version.

Cloudflare deployment

Result	Cause and recovery
The browser app returns 404 or an API-only response	Run `pnpm build:web:rooms` before deploying the app Worker.
The first request fails after you deploy	Retry for up to one minute. A new Worker origin can take a short time to become ready.
Workspaces fails because the Artifacts binding is missing	Enable Artifacts, create the namespace through a bootstrap repository, and use the same namespace in both Worker configs. There is no supported fallback store.
Access never shows a login screen	Use a custom domain and confirm the Access application covers the app origin. The default `workers.dev` address is only for pre-Access checks.
Workspaces returns `401` after Access	Confirm the Access team domain and application audience in the app Worker config.
An API-key or Git request opens an Access screen	Use the public API origin. Remove that origin from the Access application. Only the browser app host belongs behind Access.
A raw link returns `200 text/html`	The request reached the app Worker. Deploy the required usercontent Worker, use a separate origin, and set the app’s `USERCONTENT_ORIGIN` to it.
A raw link asks for Cloudflare Access	Remove Access from the usercontent origin. Protect only the browser app host. Leave the public API and usercontent hosts outside Access.
A manual WebSocket check fails over HTTP/2	Repeat the `curl` check with `--http1.1`. Browser WebSockets do not need this option.

Collect safe support details

Include these facts in a support request:

container image version and source commit from /healthz, or both Worker source commits;
the failing route without its query string or share credential;
the HTTP status and content type;
the deployment type and auth mode; and
the relevant error line with private values removed.

Do not send environment files, secret values, API keys, cookies, Access assertions, callback codes, account IDs, private hostnames, or raw share URLs.

Container backup and restore

Restore a cold or hot backup into a fresh volume.

API, MCP, and Git errors

Fix authentication and agent connection errors.

Reviewed July 22, 2026. Maintained by the Plannotator documentation team.

Start

Accounts and organizations

Sharing and access

Documents and collaboration

Agents and developer access

Plans, billing, and seats

Self-hosting and updates

Security and privacy

Troubleshooting

Container boot and health

API keys

Backup, restore, and update

Cloudflare deployment

Collect safe support details

Container backup and restore

API, MCP, and Git errors

​Container boot and health

​OIDC sign-in

​API keys

​Backup, restore, and update

​Cloudflare deployment

​Collect safe support details

Container backup and restore

API, MCP, and Git errors

Container boot and health

OIDC sign-in

API keys

Backup, restore, and update

Cloudflare deployment

Collect safe support details