Sign Up

Troubleshooting

Common issues and solutions for the Thotis RAG platform.

Agent not responding

Symptoms: The agent returns no response or times out.

Possible causes:

  1. RagFlow is down: Check the health status in the RAG console dashboard. If RagFlow shows "unhealthy", check the Coolify deployment.
  2. Circuit breaker open: After 5 consecutive failures, the RagFlow client stops sending requests for 30 seconds. Wait and retry.
  3. No published version: Ensure the agent has a published version. Draft versions are not served to users.

Resolution: Check the Deployments page for failed deployments. Verify RagFlow health at /health endpoint.

Empty or incomplete responses

Symptoms: The agent responds but the content is empty, truncated, or irrelevant.

Possible causes:

  1. No datasets bound: The agent has no knowledge base to search. Bind at least one dataset in the Sources tab.
  2. Dataset not indexed: Documents were uploaded but parsing/indexing is incomplete. Check dataset status in RagFlow.
  3. Chunk size too small: Very small chunks may lack context. Consider increasing chunk size to 500-800 tokens.
  4. System prompt too long: An overly long system prompt leaves less room for retrieved context and the answer.

Slow responses

Symptoms: Responses take more than 5 seconds for simple questions.

Possible causes:

  1. Large datasets: Retrieval over very large datasets takes longer. Consider splitting into focused, smaller datasets.
  2. High temperature: Higher temperature values can lead to longer generation times. Try lowering to 0.1.
  3. Max tokens too high: Reduce max_tokens if responses are unnecessarily long.
  4. Network latency: Check the latency between the backend and the RagFlow instance.

Target performance:

  • Session creation: 100-300ms
  • First chunk visible: 800ms-2.5s
  • Short answer complete: 2-6s
  • Complex answer complete: 4-10s

Publish failures

Symptoms: The publish action fails with an error.

Common errors:

  • "System prompt is required" — Add a system prompt before publishing.
  • "At least one dataset must be bound" — Bind a dataset in the Sources tab.
  • "RagFlow is unhealthy" — RagFlow is unreachable. Check the deployment.
  • "Version is not a draft" — Only draft versions can be published.

Widget not loading

Symptoms: The embed widget does not appear on the website.

Possible causes:

  1. Wrong agent key: Verify the agent key in the script tag matches the agent's key in the console.
  2. Domain not allowlisted: Add the website's origin to RAG_EMBED_ALLOWED_ORIGINS.
  3. CORS error: Check the browser console for CORS-related errors. Ensure the origin is correctly formatted (protocol + domain, no trailing slash).
  4. Agent not active: The agent must be active and have a published version.

Mobile app issues

Symptoms: The mobile app shows errors or stale data after a publish.

Possible causes:

  1. Sync webhook failed: Check the Deployments page for sync delivery status.
  2. Backend not updated: The NestJS backend may not have received the latest manifest. Trigger a manual sync from the console.
  3. Socket.IO disconnection: The app may have lost its WebSocket connection. Force a reconnect by restarting the app.