Skip to content

Troubleshooting

This section holds the broad, symptom-organized diagnostics for CraftBot. Each individual page (install, quickstart, every integration, and each provider) already carries its own troubleshooting table for issues specific to that feature. The three reference pages here group problems by what you observe, so you can start from a symptom when you do not yet know which feature is at fault.

Work through the first diagnostics below before you open a specific page. They apply to every kind of problem and often tell you where to look next.

First diagnostics

Run these four checks in order. They resolve most problems on their own, and they tell you which reference page to read for the rest.

  1. Check status. Run python craftbot.py status. It reports whether CraftBot is running and whether auto-start is registered. If the process is not running, start it with python craftbot.py start and retry the action that failed.

  2. Read the logs. Every run writes a timestamped folder under logs/. Open logs/<run>/all.log for the full picture across the main agent and every sub-agent, or logs/<run>/main.log for the main agent alone. Restarting begins a fresh folder, so a problem from an earlier session is in an older folder, not the current one. Search for ERROR first, then read upward from the match. See Logs for the file layout, the subsystem tags, and grep recipes.

  3. Check the action panel. When a single action fails, the action panel in the interface shows the task and its status. A task that reads paused is waiting for your decision, not stuck. A task that reads error names the action that broke, which you can then trace in the logs.

  4. Restart. Run python craftbot.py restart. A restart re-reads settings, re-scans the memory index, and clears a stale lock left by a previous crash. If a restart fixes the problem, the logs from before it explain why.

Symptom router

Find your symptom, then open the page in the right column.

Symptom Go to
CraftBot will not install, launch, or build the interface Install, then Runtime issues
A port is already in use, or the service will not auto-start Runtime issues
The agent does not reply, or a task hangs Runtime issues
A task stops early or asks whether to continue Runtime issues
The agent does not recall something you told it Runtime issues
A schedule did not fire Runtime issues
Connecting an integration fails at the OAuth step Integration issues
A connected integration stops delivering messages Integration issues
An MCP server will not start, or its tools are missing Integration issues
A problem specific to one service (a scope, a rate limit) The integration's own page, from Integrations
The agent errors with 401, invalid key, or model not found Provider issues
The agent is rate limited, or slow Provider issues
A ChatGPT or SuperGrok subscription will not sign in Provider issues
An image or video action fails Provider issues

Where to get help

If the logs do not explain the failure and none of the pages match, ask for help. Include the relevant lines from logs/<run>/all.log, your provider, and your platform.

Next