Skip to content

Troubleshooting

App fails during startup

Check environment variables first. The app creates external clients from app/core/dependencies.py during import, so bad Supabase, Pinecone, or OpenAI settings can fail before the server starts serving traffic.

403 Forbidden on admin routes

require_admin only accepts JWTs whose role resolves to admin. Verify:

  • the bearer token is valid
  • app_metadata.role or fallback user_metadata.role is admin
  • the role taxonomy migrations have been applied

401 Authentication failed

Validate:

  • SUPABASE_URL
  • SUPABASE_SERVICE_ROLE_KEY
  • the client is sending Authorization: Bearer <token>

Protected endpoints use Supabase token verification on every request.

Retrieval returns weak or empty answers

Check all of the following:

  • the target Pinecone namespace exists
  • the document status is ready
  • lexical search RPC search_chunks_lexical is present in the database
  • the reference and document grade/subject fields produce the expected grade-<grade>-<subject> namespace

Also inspect usage_logs to see retrieval_query, retrieved_count, and used_count.

Ingestion jobs stay queued

This branch does not define a separate worker. A queued job only starts when /admin/jobs/dispatch is called and the API process is alive to execute the background task.

Scrape sync succeeds but nothing is queued

Inspect ingestion_handoffs:

  • completed handoff with ingestion_job_already_active means a job already exists
  • completed handoff with ingestion_job_already_completed means the payload is already ingested
  • failed handoffs usually point to invalid reference state or transient queueing issues

Reservation cleanup does not happen

The scheduler is registered in app/main.py, but the current reconciliation implementation in app/services/background_jobs.py is not aligned with the wallet service API. If expired reservations accumulate, handle them manually in the database until that code is corrected and verified.

Metrics endpoint is sparse

Metrics are stored in-memory by app/core/metrics.py. They reset on deploy and are only populated where explicit helper calls exist. Empty or low-volume metrics do not necessarily mean the API is idle.

Docs or OpenAPI seem stale

Use the router code in app/api/routers/ as the contract of record. The checked-in openapi.json, historical docs, and archived plans can lag the implementation.