Skip to main content

Troubleshooting

Compose fails to start​

docker compose ps
docker compose logs --tail=200

Common causes:

  • Missing .env variables.
  • Port conflicts on 3000, 3002, or 8000.
  • Backend cannot connect to Supabase/Postgres/Redis.
  • Frontend build-time public env values are missing.

Auth fails or redirects incorrectly​

Inspect:

  • apps/webapp/src/app/auth/*
  • apps/webapp/src/lib/oidc.ts
  • apps/webapp/src/services/api.ts
  • backend/core-api/app/core/auth.py
  • backend/core-api/app/core/config.py

Verify issuer, audience, callback URL, cookie host, and Supabase/OIDC env values.

API returns 401/403​

Check whether the route expects:

  • Authorization: Bearer <token>
  • access_token cookie
  • X-API-Key

Backend auth helpers live in:

  • backend/core-api/app/core/auth.py
  • backend/core-api/app/core/api_key_auth.py
  • backend/core-api/app/core/rbac_deps.py

Docusaurus build fails​

Docusaurus 3 uses strict MDX. Keep JSON/YAML/TypeScript examples in fenced code blocks and avoid unescaped JSX-like text in Markdown.

Run:

npm run docs:typecheck
npm run docs:build