Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IstiqlalBhat/aiagent/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the most common issues you may encounter when using Agentic AI and their solutions.

​
Call Issues

Symptoms: Outbound calls fail to connect or incoming calls aren’t answered.Solutions:
  1. Verify Twilio credentials: 
    # Check your .env file
cat .env | grep TWILIO
    Ensure TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER are correctly set.
  2. Confirm Twilio phone number is voice-enabled:
    • Go to Twilio Console → Phone Numbers
    • Verify your number has “Voice” capability
  3. Check webhook URL configuration: 
    # Test if your webhook URL is accessible
curl https://your-ngrok-url.ngrok.io/health
    The webhook must be publicly accessible for Twilio to reach it.
  4. Verify ngrok/tunnel is running: 
    # Check if ngrok is active
curl http://localhost:4040/api/tunnels
For incoming calls, ensure your Twilio number webhook is set to https://your-url.ngrok.io/twilio/voice
Symptoms: Call connects but no audio is heard, or AI doesn’t respond.Solutions:
  1. Verify OpenAI Realtime API access: 
    # Check if API key is set
echo $OPENAI_API_KEY
    Ensure your OpenAI account has access to the Realtime API.
  2. Confirm model configuration: Check config.yaml for correct model name: 
    openai_realtime:
  enabled: true
  model: "gpt-4o-realtime-preview-2024-12-17"
  voice: "alloy"
  3. Check for WebSocket errors: 
    agenticai service logs -f | grep -i "websocket\|audio\|openai"
  4. Verify audio format compatibility: The service uses mulaw 8kHz audio. Check logs at /tmp/agenticai/agenticai.log for audio conversion errors.
If using Gemini instead of OpenAI, ensure gemini.api_key is valid and the model supports native audio
Symptoms: Calls start successfully but disconnect after a few seconds or minutes.Solutions:
  1. Check server stability: 
    agenticai service status
    Ensure the service is running and not crashing.
  2. Review error logs: 
    tail -n 100 /tmp/agenticai/agenticai-error.log
    Look for exceptions or connection errors.
  3. Verify WebSocket connection stability: Check for timeout or connection reset errors in logs: 
    grep -i "timeout\|reset\|closed" /tmp/agenticai/agenticai.log
  4. Increase timeout values: If you’re experiencing timeouts, the WebSocket may be closing due to inactivity. Check your tunnel provider’s timeout settings.
Free ngrok tunnels have session limits. Consider using a paid plan or Cloudflare tunnels for production

​
Configuration Issues

Symptoms: Error messages about missing credentials or “Configuration file not found”.Solutions:
  1. Verify .env file exists: 
    ls -la .env
    If missing, copy from template: 
    cp .env.example .env
  2. Check file location: The .env file must be in the project root directory where you run agenticai commands.
  3. Validate environment variable format: 
    # Correct format (no spaces around =)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Incorrect format
TWILIO_ACCOUNT_SID = ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  4. Source environment variables: 
    # Load environment variables
export $(cat .env | xargs)
Use the setup wizard for guided configuration: agenticai setup
Symptoms: “Authentication failed”, “Invalid API key”, or “Unauthorized” errors.Solutions:
  1. Test each API key individually: Twilio: 
    agenticai test-connection
    OpenAI: 
    curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
    Gemini: 
    curl "https://generativelanguage.googleapis.com/v1/models?key=$GEMINI_API_KEY"
  2. Regenerate API keys:
  3. Check for hidden characters: 
    # Remove any whitespace from API keys
sed -i 's/ //g' .env
Never commit .env files to version control. Use .env.example for templates only
Symptoms: “Address already in use” error when starting the server.Solutions:
  1. Check what’s using the port: 
    lsof -i :8080
# or
netstat -tulpn | grep 8080
  2. Kill the process: 
    # Kill process by port
kill -9 $(lsof -t -i:8080)
  3. Use a different port: 
    agenticai server --port 8081
    Or update config.yaml: 
    server:
  port: 8081
  4. Stop existing service: 
    agenticai service stop

​
Integration Issues

Symptoms: AI acknowledges commands but ClawdBot doesn’t execute them.Solutions:
  1. Verify OpenClaw Gateway is running: 
    # Check if gateway is accessible
curl -I ws://127.0.0.1:18789
  2. Ensure ClawdBot agent is started: 
    clawdbot agent --session-id agent:main:main
  3. Check gateway URL in config: 
    # In config.yaml
gateway:
  url: "ws://127.0.0.1:18789"
  4. Test gateway connection: 
    agenticai bot
# Then type: status
  5. Verify ClawdBot skills are configured: Check that the specific skills (YouTube, Spotify, Email) are properly configured in ClawdBot.
Gateway integration is optional. Comment out gateway client initialization in call_manager.py:92-99 if not using ClawdBot
Symptoms: Call transcripts and commands aren’t appearing in Telegram.Solutions:
  1. Verify bot token and chat ID: 
    # Check credentials
echo $TELEGRAM_BOT_TOKEN
echo $TELEGRAM_CHAT_ID
  2. Test bot API access: 
    curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe"
  3. Get your correct chat ID:
    • Message your bot on Telegram
    • Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
    • Find "chat":{"id":123456789}
  4. Enable Telegram in config: 
    telegram:
  enabled: true
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: ${TELEGRAM_CHAT_ID}
  5. Check for message sending errors: 
    grep -i "telegram" /tmp/agenticai/agenticai-error.log
Send a test message: agenticai test-connection will verify Telegram connectivity

​
Service Management Issues

Symptoms: Service fails to start or restarts repeatedly.Solutions:
  1. Check service status: 
    agenticai service status
  2. Review crash logs: 
    tail -n 50 /tmp/agenticai/agenticai-error.log
  3. Verify all dependencies are installed: 
    pip install -e .
  4. Check Python version: 
    python --version
# Requires Python 3.11+
  5. Test server manually: 
    # Run in foreground to see errors
agenticai server
  6. Reinstall the service: 
    agenticai service uninstall
agenticai service install --webhook-url https://your-url.ngrok.io
agenticai service start
The service requires a permanent webhook URL. Free ngrok URLs expire and require updating the service configuration
Symptoms: ngrok or Cloudflare tunnel fails to connect or URL changes.Solutions:
  1. For ngrok: 
    # Check if ngrok is running
curl http://localhost:4040/api/tunnels

# Restart ngrok
agenticai tunnel start
  2. For Cloudflare tunnels: 
    # Start Cloudflare tunnel
agenticai tunnel start --provider cloudflare
  3. Use a permanent tunnel URL:
    • ngrok: Upgrade to paid plan for fixed domains
    • Cloudflare: Create named tunnel: cloudflared tunnel create agenticai
  4. Update service with new URL: 
    agenticai service uninstall
agenticai service install --webhook-url https://new-url.ngrok.io
  5. Set environment variable: 
    export NGROK_URL=https://your-url.ngrok.io
For production deployments, use a permanent URL with a custom domain to avoid reconfiguration

​
Getting Help

If you’re still experiencing issues:
  1. Check service logs: agenticai service logs -f
  2. Run diagnostics: agenticai test-connection
  3. Review recent errors: tail -n 100 /tmp/agenticai/agenticai-error.log
  4. Report issues: GitHub Issues
Include relevant log excerpts and your configuration (with sensitive data removed) when reporting issues

Build docs developers (and LLMs) love

Get started for freeTalk to us