Common Issues
Deployment problems in Kanera are usually configuration rather than code: a domain pointed at the wrong service, a cookie setting that does not match the public URL, or a secret that changed between deploys.
Work through a new deployment in order
For a deployment that has never worked, check these in sequence rather than jumping to the symptom:
- Confirm the required environment variables are present. See Create the environment file.
- Check that PostgreSQL and Valkey are healthy.
- Check the API and worker logs.
- Confirm the public health endpoints respond. See Check the deployment.
- Verify reverse-proxy routing and trusted public URLs. See Services and Routing.
- Test SMTP, storage, and backup configuration separately.
Each step depends on the ones above it, so a failure at step 4 is rarely worth debugging before step 2 passes.
Symptoms and checks
| Problem | What to check |
|---|---|
| Users are signed out after login. | Confirm COOKIE_SECURE=true, COOKIE_DOMAIN, and WEB_ORIGIN match the public HTTPS domain. |
| Everyone was signed out after a deploy. | JWT_SECRET changed. Restore the previous value. |
| Authenticator codes stopped working for every enrolled user. | MFA_ENCRYPTION_KEY changed. Restore the previous value. |
/api/health fails on the web domain. | Confirm the domain routes to the web service on port 80, not directly to api. |
| Public API does not respond. | Confirm the domain routes to public-api on port 3001. |
| MCP does not respond. | Confirm the domain routes to mcp on port 3002, MCP_SERVER_PUBLIC_URL points at the public /mcp URL, and KANERA_PUBLIC_API_URL is http://public-api:3001 inside compose. |
| MCP is healthy but every OAuth request fails. | Confirm MCP_PUBLIC_URL is the exact public /mcp resource and MCP_INTERNAL_SECRET is the same non-JWT value in public-api and mcp. After upgrading from unbound OAuth tokens, reconnect each client once. |
| Rate limits affect everyone at once. | Confirm API_TRUST_PROXY=true and PUBLIC_API_TRUST_PROXY=true when behind a trusted proxy. |
| Email verification blocks users. | Leave EMAIL_VERIFICATION_ENABLED=false until SMTP is working. |
| No email arrives at all. | Check SMTP values and the worker logs. Email is sent by the worker service, not the API. |
| Uploads disappear after redeploy. | Confirm kanera_uploads is persistent or configure S3-compatible storage. |
| Attachments no longer open. | MEDIA_SIGNING_SECRET changed, invalidating existing signed URLs. |
| A chat destination or personal webhook stopped working after a deploy. | SECRETS_ENCRYPTION_KEY changed, so stored credentials can no longer be decrypted. Restore the previous value. |
| Browser push cannot be enabled. | Confirm HTTPS, then that an organisation admin has enabled organisation push. See Email and Notifications. |
| A user cannot save an ntfy or Gotify address on the internal network. | Private receivers are refused unless KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true. |
Deployment reference
The implementation-backed deployment reference is DEPLOY.md.
For problems inside the app rather than the deployment — sign-in, permissions, notifications, integrations, uploads — start from Troubleshooting.
Ask for help
When reporting a deployment problem, include:
- What you were trying to do, and the page or control you used.
- What you expected and what happened instead.
- Relevant service logs with secrets removed.
- Whether the deployment is new or previously working.
- Browser and operating-system versions when relevant.
Email [email protected] for support or open a GitHub issue for a reproducible software or documentation problem. Never include passwords, API keys, tokens, customer data, or private attachments.