Skip to content

Troubleshooting Guide

This guide covers common issues and how to resolve them when running ravenbot.

🔍 Log Files

The first step in troubleshooting any issue is checking the logs.

  • Docker: 
    docker compose logs -f ravenbot
  • Local (Files): Check the logs/combined.log file in the project root. Falls back to stdout-only if the file can't be opened.

Set LOG_LEVEL=debug for verbose logging including ADK events, session lifecycle, and HTTP request details.

❌ Common Issues

1. Bot doesn't respond to messages

  • Cause: Incorrect TELEGRAM_CHAT_ID or DISCORD_CHANNEL_ID.
  • Solution: The bot is locked to specific IDs for security. Ensure these IDs are correct in your .env. Check the startup logs for unauthorized ID warnings.

2. "Restricted IP" or "SSRF Protection" errors

  • Cause: Trying to access a local service (like Ollama on localhost).
  • Solution: Set ALLOW_LOCAL_URLS=true in your .env. In Docker, use http://host.docker.internal:11434/v1 instead of localhost.

3. MCP tool not found or failing

  • Cause: Missing node or npm, or an incorrect command in config.json.
  • Solution: Most MCP servers require Node.js. In Docker, these are pre-installed. For local runs, ensure node and npm are in your $PATH.

4. Database Locked Errors (database is locked)

  • Cause: Too many concurrent writes.
  • Solution: ravenbot uses a single writer connection pool. Ensure you aren't running multiple instances against the same ravenbot.db file.

5. Web UI not loading

  • Cause: Port conflict or misconfiguration.
  • Solution: Check that port 8080 (or your WEB_PORT) is not in use by another service. Check logs for "Web server starting" message.

6. Web UI templates not rendering (blank pages or raw Go code)

  • Cause: Templ templates not generated.
  • Solution: Run make templ (or templ generate ./...) to regenerate Go code from .templ files. This is done automatically by make build.

7. Permission denied errors in Docker (data/, logs/)

  • Cause: Docker creates bind-mounted host directories as root.
  • Solution: The entrypoint.sh script handles this automatically by chown-ing the directories before dropping to ravenuser. If you see this error, ensure your Docker image was rebuilt after the entrypoint was added (docker compose build).

8. Mission stuck in "running" status

  • Cause: The mission goroutine may have timed out or crashed.
  • Solution: Missions have a 10-minute timeout. If it's been longer, the process likely restarted. Use /reset to clear stale sessions, or check logs for the mission ID.

9. Compression threshold misconfigured

  • Cause: compressionThreshold in config.json is outside 0–1.0 range.
  • Solution: The value is validated on load and defaults to 0.8 if invalid. Check startup logs for a warning about the threshold value.

🛠 Advanced Diagnostics

Reset the Session

If the bot is "stuck" in a specific conversation: 

/reset
This clears the current conversation context, summary cache, and session.

Check System Metrics

Use /status to verify that the host system is healthy and that the sysmetrics MCP tool is working correctly.

Regenerate Templates

If the web UI behaves unexpectedly after code changes: 

make templ   # Regenerate templ files
make build   # Rebuild

Token Limit Exceeded

If you get errors about context length: - Lower the compressionThreshold in config.json (e.g., 0.6 for earlier compression). - The bot automatically compresses history asynchronously when the threshold is exceeded.

🐛 Reporting a Bug

If you've found a persistent issue: 1. Check the Issues page. 2. Provide your go version, docker --version, and OS/platform. 3. Include relevant log output (redact any API keys!). 4. Mention whether you're using Gemini or Ollama backend.