🛠️ Troubleshooting
🛠️ Troubleshooting
Troubleshooting
Use this page to find the right guide for your issue. If you're unsure where to start, match your symptom in the table below.
🔌 Connection Errors📈 Performance📄 RAG🔐 SSO & Auth🎤 Audio⚖️ Scaling & HA
Quick Symptom Lookup
| What you're seeing | Go to |
|---|---|
Empty "{}" responses, garbled markdown, CORS errors in console | Connection Errors → HTTPS/CORS/WebSocket |
WebSocket connection failed: 403 or chat hangs | Connection Errors → WebSocket |
| Can't connect to Ollama from HridaAI | Connection Errors → Ollama |
Model list takes forever to load / 500 on /api/models | Connection Errors → Model List Loading |
[SSL: CERTIFICATE_VERIFY_FAILED] | Connection Errors → SSL |
| Login loops, 401 Unauthorized, token errors across replicas | Scaling & HA → Login Loops |
database is locked, data disappearing across instances | Scaling & HA → Database |
Worker crash: Child process [pid] died during upload | RAG → Worker Crashes |
| Model ignores attached knowledge base | RAG → Knowledge Base Not Working |
Agent stops mid-task after many tool calls / Tool-call limit reached (N iterations). | CHAT_RESPONSE_MAX_TOOL_CALL_ITERATIONS |
NoneType object has no attribute 'encode' | RAG → Embedding Error |
| CUDA out of memory during embedding | RAG → CUDA OOM |
| OAuth redirect loops, CSRF state mismatch | SSO & OAuth |
CSRF Warning! State not equal in request and response | SSO → CSRF Errors |
TTS loading forever, Dataset scripts are no longer supported | Audio → TTS Issues |
Whisper int8 compute type error | Audio → STT Issues |
| Microphone not working (non-HTTPS) | Audio → Microphone |
| Image not generating, ComfyUI workflow errors | Image Generation |
| Web search returns empty content or proxy errors | Web Search |
| Slow performance, high RAM, OOM crashes | Performance & RAM |
| Container OOM-killed when editing model/knowledge permissions (SQLite) | Performance & RAM → SQLite Memory Footprint |
| "The prompt is too long" / context length exceeded | Context Window / Prompt Too Long |
| Forgot admin password | Reset Admin Password |
no such table or table already exists on startup | Database Migration |
All Troubleshooting Guides
| Guide | Covers |
|---|---|
| Connection Errors | HTTPS, CORS, WebSocket, reverse proxy, Ollama, SSL, Podman, MCP |
| Performance & RAM | Speed tuning, database optimization, scaling infrastructure, resource efficiency |
| Context Window / Prompt Too Long | Why "prompt is too long" errors happen and how to manage chat history with filters |
| RAG | Document ingestion, retrieval quality, embeddings, upload limits, worker crashes |
| SSO & OAuth | OIDC, Microsoft, Google, Authentik, cookie & session issues |
| Audio | Speech-to-Text, Text-to-Speech, microphone access, ElevenLabs |
| Scaling & HA | Multi-replica, multi-worker, Redis, shared storage, database concurrency |
| Image Generation | OpenAI, ComfyUI, Automatic1111, Gemini |
| Web Search | Proxy issues, SearXNG, empty results, timeouts |
| Reset Admin Password | Password reset for Docker and local installations |
| Database Migration | Manual Alembic migrations, recovery from failed upgrades |
Before You Start
💡 Tips
- Update first. Many issues are fixed in newer releases. Make sure you're on the latest version.
- Check ConfigVar. HridaAI stores some settings in its database, which take priority over environment variables. If an env var change seems ignored, see the Environment Variable Configuration page.
Browser Compatibility
HridaAI requires a modern browser. Minimum supported versions:
🌐 Chrome 111+ March 2023
🧭 Safari 16.4+ March 2023
🦊 Firefox 128+ July 2024
If you experience rendering or functionality issues, ensure your browser meets these requirements.
Get Support
If you're still stuck after following the relevant guide, contact the Zlabs Innovation support team at hello@hrida.ai or visit the Enterprise page for dedicated support options.