Troubleshooting

Local services do not start

• Confirm Docker is running and the configured ports are available.
• Run corepack pnpm infra:up from the repository root.
• If this is a new checkout, run corepack pnpm dev:setup once before starting the other services.
• After changing database schema, run corepack pnpm db:migrate.

Sign-in returns to the login page

Check that the configured OIDC issuer’s /.well-known/openid-configuration endpoint is reachable and that the web app and API use the same issuer. For local development, Keycloak should be healthy and the callback must be http://127.0.0.1:13000/auth/callback.

An invitation cannot be accepted

Invitations expire after seven days and are single-use. The invitee must authenticate with the same verified email address the organization invited. Ask an owner or admin to create a new invitation if the old one expired or was revoked.

No credential email arrives

Email delivery is disabled by default. Local and self-hosted deployments need SMTP settings; hosted Cloudflare delivery also needs a Hyperdrive binding, a verified Resend sender, RESEND_API_KEY, and the encryption key secret. Check the credential’s email delivery state in the organization workspace. You can create a fresh claim link and share it directly if email is unavailable.

A credential is not shown as valid

The public page separately reports signature, expiration, and revocation status. A revoked or expired credential is not valid. If revocation status is unavailable, retry once the public status-list endpoint is reachable; an unavailable status check is not considered valid.