Troubleshooting¶
Common Issues¶
Bot doesn't respond to messages¶
Symptoms: Send voice messages but get no response.
Check:
-
Is your chat ID in
ALLOWED_CHAT_IDS?# Find your chat ID curl "https://api.telegram.org/bot<TOKEN>/getUpdates" -
Is the bot running?
journalctl -u voice-agent -f -
Is the token correct?
# Test with curl curl "https://api.telegram.org/bot<TOKEN>/getMe"
"Transcription failed" errors¶
Symptoms: Bot receives audio but can't transcribe.
Check:
-
Is whisper-server running?
curl http://localhost:8080/health -
Is
WHISPER_URLcorrect?curl -X POST -F "file=@test.ogg" http://localhost:8080/transcribe -
Is the audio format supported? Telegram sends
.oga(Opus in Ogg).
"claude CLI not found"¶
Symptoms: Transcription works but Claude doesn't respond.
Check:
-
Is Claude CLI installed?
which claude claude --version -
Is Claude CLI authenticated?
claude login -
Is Claude CLI in the service's PATH?
Permission requests never complete¶
Symptoms: Asked to approve but approval doesn't work.
Check:
- Say the exact keywords: "yes", "approve", "ok"
- Check for pending permissions: say "status"
- Approval might have timed out (default: 5 minutes)
Session state is wrong¶
Symptoms: Claude seems confused or in wrong directory.
Fix: Say "new session" to reset.
Debug Mode¶
Enable verbose logging:
import logging
logging.basicConfig(level=logging.DEBUG)
Or set environment:
export PYTHONUNBUFFERED=1
export LOG_LEVEL=DEBUG
Log Locations¶
| Method | Location |
|---|---|
| Direct run | stdout |
| systemd | journalctl -u voice-agent |
| Docker | docker logs voice-agent |
Getting Help¶
- Check logs for error messages
- Try "status" command to see session state
- Say "new session" to reset
- Restart the service if needed
Known Limitations¶
- No voice responses: Output is text only
- Single session per chat: Can't run parallel Claude sessions
- Memory-based sessions: Sessions don't persist across restarts
- No image support: Can't process screenshots or images