Troubleshooting Guide

Bot not responding?

Start with the dedicated checklist for silent bots and missing replies.

Open the checklist →

Startup Crash: "imsg rpc exited with code 1"

The most common startup error. Usually caused by port conflicts or Node.js version.

Fix startup crash →

Gemini 2.0 Flash No Response

Fix hallucinations and fake tool calls with Gemini models.

Fix Gemini issues →

Windows Defender Blocked Install

How to bypass SmartScreen and install safely on Windows.

Unblock installer →

Docker: "permission denied"

This happens on Linux if your user isn't in the `docker` group.

sudo usermod -aG docker $USER && newgrp docker

Run this command and try again.

"API Key Invalid" or 401 Error

Ensure you copied the full key starting with `sk-ant-...`.

Check your balance at console.anthropic.com. You must have credits (not just a free tier account with $0 balance).

VNC Connection Refused (localhost:5900)

If the container is running but you can't connect:

  • Check if port 5900 is blocked by a firewall (especially on VPS).
  • Use the web interface at http://localhost:8080 instead.
  • Restart Docker Desktop.

Still stuck? Check GitHub Issues