Troubleshooting Guide
This section covers common issues, root causes, and recommended solutions when developing or running applications on chakra-convai.
Diagnostic Matrix
| Symptom | Likely Cause | Recommended Resolution |
|---|---|---|
pip cannot find chakra-convai |
The install token is missing or invalid, or the system is not Linux x86_64 with Python 3.12 | Verify FURY_DEPLOY_TOKEN is set in the environment. On Windows or macOS, build and run inside Docker or WSL. |
Install fails while building annoy |
Missing C++ compiler toolchain | Use the full python:3.12 base image or install g++ (apt-get install -y build-essential). |
"Chakra Console licence check failed" at start |
CHAKRA_LICENSE_KEY is missing, suspended, or outbound network access is blocked |
Check your key in .env. Run chakra-convai licence to inspect status. Contact Chakra Labs if suspended. |
chakra-convai check reports a missing instruction key |
A required key is missing or empty in config/instructions.json |
Review the error output from chakra-convai check and add the missing keys. |
A skill's tools are missing |
The skill failed to import, or the directory lacks __init__.py or tool.py |
Run chakra-convai check to view the import traceback. |
The agent never answers incoming calls |
AGENT_NAME does not match the LiveKit dispatch rule, or LiveKit credentials are wrong |
Ensure [[agents]] name in chakra.toml matches your SIP dispatch rule in LiveKit Cloud. |
A different pipeline runs than configured |
The license does not permit the requested pipeline | Run chakra-convai check to view allowed pipelines. Request pipeline additions in Chakra Console. |
The agent is silent on Chakra Voice |
The response is in a language not supported by Chakra Voice | Chakra Voice speaks Sinhala. For Tamil or English voice sessions, use the gemini_live pipeline. |
A Console update has no effect |
The periodic sync cycle has not elapsed | Wait up to 10 minutes for running workers to synchronize with Chakra Console. No redeploy is needed. |
Daily talk-time limits are ignored |
DATABASE_URL is unset, or caller identity is anonymous |
Verify PostgreSQL connectivity ([features] database = true). Ensure caller ID is detected. |
Returning callers are not recognized |
Caller memory is unconfigured or was never saved on the previous call | Verify save_caller_memory is in [tools] builtin and database connectivity is operational. |
Knowledge base queries return empty results |
Documents are marked as drafts (name starts with _), index not built, or GOOGLE_API_KEY missing |
Rename drafts, verify GOOGLE_API_KEY, and run chakra-convai build-rag. |
Uploaded voice shows "Could not be used" |
Audio file is not 5–10 seconds, is silent, or does not match transcript text | Upload a clean, noise-free .wav clip and ensure transcript words match the spoken audio exactly. |
Contacting Support & Reporting Issues
When requesting assistance from Chakra Labs support: 1. Provide the output of:
2. Include the timestamp of the affected call, along with thesession_id and error logs.
3. Security Caution: Never share your CHAKRA_LICENSE_KEY or FURY_DEPLOY_TOKEN in support chats, tickets, or public issue trackers.