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.

� Sentry Error Tracking

If SENTRY_DSN is configured, all slog.Error calls and HTTP panics are automatically forwarded to Sentry. This is the fastest way to catch errors in production without tailing logs.

  • Check your Sentry project's Issues tab for grouped error reports.
  • Each issue includes the static log message (e.g. "ADK runner error") as a tag, making it easy to filter.
  • Panics from HTTP handlers appear as level=fatal with path and method tags.
  • To verify Sentry is active, look for "Sentry initialized" in startup logs.

If errors are not appearing in Sentry: - Confirm SENTRY_DSN is set and the container was rebuilt after adding it. - Check that Sentry's ingestion endpoint is reachable from your server. - sentry.Flush(5s) runs on shutdown — events buffered just before a crash may not send if the process is killed with SIGKILL.

�🐛 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.