Troubleshooting

Run diagnostics first

When something isn't working, start here:

babyclaw doctor

This checks your config, database, Telegram connection, and AI provider setup. It'll tell you what's wrong.

Common issues

"Config validation failed"

The gateway won't start if the config file has errors. Common causes:

• Unknown keys -- BabyClaw uses strict validation. Typos in key names will be rejected.
• Wrong types -- e.g., a string where a number is expected.
• Missing required fields -- version, ai.providers, and ai.models.chat are all required.

Run babyclaw config validate to see the exact errors.

Bot not responding on Telegram

Check these in order:

1. Is the gateway running? Run babyclaw service status or babyclaw gateway status.
2. Is the bot token correct? Make sure channels.telegram.botToken matches what BotFather gave you.
3. Did you message the right bot? Search for your bot's username in Telegram.
4. Check the logs. If the gateway is running but the bot isn't responding, look at the log output for errors. The default log output is stdout.

"At least one provider must be configured"

You need at least one entry in ai.providers with a valid API key. See AI Providers.

Model errors / API key issues

If the agent starts but fails on the first message:

• Check that the model string matches the format provider:modelId (e.g., anthropic:claude-sonnet-4-20250514)
• Check that the provider name in the model string matches a key in ai.providers
• Verify your API key is valid and has credit/quota

Database errors

BabyClaw uses SQLite with Drizzle. The database file is created automatically at <workspaceRoot>/.data/babyclaw.db.

If you see database errors:

• Make sure the directory exists and is writable
• If the database is corrupted, you can delete the .db file and let BabyClaw recreate it (you'll lose session history and schedule data)

Schedules not firing

• Check that the gateway is running continuously (schedules only fire while the gateway is up)
• Verify the timezone in scheduler.timezone is correct
• Check babyclaw gateway status to see if the scheduler is active

Heartbeat not running

• Make sure heartbeat.enabled is true in the config
• Check activeHours -- heartbeats are skipped outside the active window
• The minimum interval is 5 minutes
• Use /heartbeat in Telegram to check the status

Debug logging

For more detail on what's happening, set the log level to debug:

{
  "logging": {
    "level": "debug"
  }
}

This produces a lot of output but can help track down issues. Set it back to "info" when you're done.

Redacting sensitive data from logs

If you're sharing logs for debugging, you can redact specific fields:

{
  "logging": {
    "redact": ["apiKey", "botToken"]
  }
}

Getting help

BabyClaw is a small project. If you're stuck, check the GitHub issues or open a new one with:

• Your config (with API keys removed)
• The error message or log output
• What you expected to happen