Skip to content

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:

chakra-convai version
chakra-convai check
2. Include the timestamp of the affected call, along with the session_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.