Troubleshooting

Common issues and fixes for BodhAI.

Troubleshooting

"Server offline" at {slug}.bodhai.app

The Cloudflare Tunnel is not connected. Check:

  1. The BodhAI server is running on the host machine
  2. The cloudflared daemon is running: on Mac check System Settings → General → Login Items; on Linux run systemctl status cloudflared
  3. The host machine has internet access
  4. If everything looks right, restart the server: bodhai restart (Mac) or sudo systemctl restart bodhai (Linux)

If you are in the office, use the LAN URL (http://<server-ip>:8742) as a fallback — it works without internet.

Chat answers are slow

Normal response times: 3–15 seconds for most queries, up to 60 seconds for complex agentic queries.

If responses are consistently taking more than 30 seconds for simple questions:

  • On Mac: check Activity Monitor — mlx_lm.server should be using GPU. If it shows CPU only, the Metal acceleration is not active. Restart the server.
  • On Linux: run nvidia-smi and confirm GPU memory is being used by the llama-server process
  • Reduce Max concurrent requests in Admin → Settings if multiple users are querying simultaneously on a lower-RAM machine

Document indexing fails

Check that the Python sidecar is running. The sidecar handles document parsing.

On Mac: curl http://localhost:7998/health — should return {"status":"ok"}

If the sidecar is down:

  • Mac: bodhai restart restarts all components including the sidecar
  • Linux: docker compose restart bodhai-sidecar

Common causes:

  • First boot: the sidecar takes 30–60 seconds to warm up on first run
  • Memory pressure: the sidecar requires ~2 GB RAM. On 16 GB machines, close other applications during heavy indexing

Login page shows "workspace not found"

Your workspace slug is not recognised by the portal. Possible causes:

  • Typo in the slug — check your welcome email for the exact workspace ID
  • Your organisation has not been provisioned yet — contact your BodhAI administrator

"Too many requests" on OTP verification

OTP verification is limited to 3 attempts per request to prevent brute force. If you exceed 3 attempts, the OTP is invalidated. Start the signup process again to receive a new code.

PPTX shows a download button instead of preview

LibreOffice is not installed on the BodhAI server. PPTX preview requires LibreOffice (soffice) to be available at the system level. The document is still fully indexed and queryable via Chat — only the preview is affected.

To enable PPTX preview: install LibreOffice on the server and restart BodhAI.

PDF generation fails ("LibreOffice is not available")

Generating PDF documents in chat requires LibreOffice on the BodhAI server (PDFs are built via an intermediate DOCX). If it is missing, the assistant says so and offers DOCX or Markdown output instead. Install LibreOffice and restart BodhAI to enable PDF output.

Image indexed with "No extractable text found"

The OCR pass found no readable printed text in the uploaded image. Common causes: the image is blank or decorative, the text is handwritten (not supported), or the photo is too low-resolution, rotated, or blurred. Re-shoot the page flat, sharp, and well-lit, or upload a text-based version of the document. See Supported File Types.

Getting help

Use the feedback button (bottom-right of any page) to submit a bug report. Reports are automatically PII-scrubbed before leaving your server. Include a description of what you were doing when the issue occurred.