Troubleshooting

Solutions to common issues you might encounter while using Opentrace.

Document Processing

Document stuck on “queued”

Cause: The Celery worker is not running or is disconnected from Redis.

• Verify the Celery worker is running: check Docker logs or terminal output
• Verify Redis is accessible: redis-cli ping should return PONG
• Check the REDIS_URL environment variable matches in both server and worker

Document stuck on “partitioning”

Cause: The file may be corrupted, password-protected, or in an unsupported format.

• Ensure the file is a valid PDF, DOCX, or HTML file
• Remove any password protection from PDFs
• Check the Celery worker logs for error details

Document shows “failed” status

Cause: An error occurred during one of the processing stages.

• Click the document to see the error message in the detail view
• Common causes: OpenAI API rate limits, S3 access issues, malformed files
• Try deleting and re-uploading the document

Chat Issues

AI says “No relevant information found”

• Ensure your documents have finished processing (status: completed)
• Try rephrasing your question with different keywords
• Lower the similarity_threshold in RAG Settings (e.g., from 0.3 to 0.2)
• Increase num_chunks to retrieve more results
• Switch to Hybrid strategy to also search by keywords

AI gives inaccurate or vague answers

• Be more specific in your questions
• Enable reranking for better chunk selection
• Try Multi-Query strategy for complex questions
• Inspect the citations to verify what context the AI received

Authentication

Can't sign in

• Clear your browser cache and cookies
• Ensure JavaScript is enabled
• Try a different browser
• Check if Clerk is experiencing any outages at status.clerk.com

API returns 401 Unauthorized

• Your JWT token may have expired — refresh the page to get a new token
• Ensure the CLERK_SECRET_KEY in the server matches your Clerk project
• Verify the Authorization: Bearer <token> header is present

Self-Hosting

Server won't start

• Check all required environment variables are set (see Environment Variables)
• Verify Python 3.12+ is installed
• Ensure Redis is running and accessible
• Check port 8000 is not already in use

Database connection errors

• Verify SUPABASE_DATABASE_CONNECTION_STRING is correct
• Ensure the Supabase instance is running and accessible
• Check if the pgvector extension is enabled
• Run the schema from notes/schema.sql if tables are missing