When something goes wrong, your first instinct might be to rebuild everything. Resist that urge. Start with the logs.
The Troubleshooting Mindset
- Read the error — What does it actually say?
- Isolate the component — Is it Slack, the AI, or Notion?
- Fix one thing at a time — Don't change three variables at once.
Step 1: Watch the Logs (Always Start Here)
docker compose logs -fThis shows you what “the brain” is thinking in real-time:
- Incoming Slack messages
- AI classification decisions
- Notion API responses (or errors)
Step 2: Identify Which Component Failed
| Error Contains | Failed Component | Next Step |
|---|---|---|
slack, xoxb, channel | Slack connection | Check tokens & bot invite |
notion, database, object not found | Notion API | Check sharing & database IDs |
openrouter, API key | AI/OpenRouter | Check API key & credits |
json, parse | AI response format | Check prompt or model |
Step 3: Common Fixes
Slack Issues
- “Auth error” → Verify
xoxb-andxapp-prefixes - Bot never receives messages → Enable Event Subscriptions (Module 3, Step 5)
- Bot doesn't respond → Run
/invite @YourBotin channel
Notion Issues
- “Could not find database” → Share the database with your integration
- “Validation error” → Check property names match exactly (case-sensitive!)
- Page created but fields empty → Verify property types match
AI/OpenRouter Issues
- “Invalid API key” → Verify key starts with
sk-or- - “Model not found” → Check model name format
- Empty responses → Add JSON response format to API call
Step 4: The Nuclear Option (Rebuild)
When in doubt, rebuild from scratch:
docker compose down && docker compose up --build -d