Troubleshooting

App won’t start

• Confirm .env is present and DATABASE_URL is reachable from the app container
• Run migrations after schema changes (migrate service in production compose, or pnpm db:push locally)
• Check Docker services: docker compose ps
• Verify ORIGIN matches your public HTTPS URL in production

Docs collaboration not working

• Ensure the collab service is running (pnpm collab:dev locally, or the collab service in production)
• Set PUBLIC_COLLAB_WS_URL to the URL clients use (e.g. ws://localhost:1234 locally, wss://your-domain/collab in production)
• Check reverse-proxy WebSocket upgrade headers if behind Caddy or nginx
• Confirm BETTER_AUTH_SECRET (or COLLAB_JWT_SECRET) is set — collab tokens depend on it

File uploads failing

• Confirm MinIO/S3 credentials and bucket name in .env
• For local dev, run pnpm db:start so minio-init creates the wrkin bucket
• Check team plan upload limits on hosted tiers

Password reset / invites not sending

• Outbound email is not configured by default. Add RESEND_API_KEY or SMTP settings and restart the app
• Verify DNS (SPF, DKIM, DMARC) for your sending domain
• See Production deployment — Environment variables

TLS / certificate errors (production)

• DNS must point at the server before Caddy requests a certificate
• Ports 80 and 443 must be open
• See Production deployment

Seed script issues

• pnpm db:seed deletes seed-owned teams and users before recreating — use only on dev/staging
• All seed users use password password123 and *@wrkin.local emails
• If login fails after seed, confirm BETTER_AUTH_SECRET has not changed mid-session (sign out and back in)

Get help

If you are stuck, email hello@wrkin.space with:

• What you expected vs what happened
• Relevant logs (app, collab, Caddy)
• Whether the issue is local dev or production

Related guides

• Local development
• Docker Compose (dev services)
• Production deployment