| name | mushi-debug |
| description | Debug Mushi Mushi issues — SDK not reporting, API errors, LLM key exhaustion, story mapping failures, QA test failures, PDCA loop not running, edge function errors. Use when "mushi is not working", "sdk not pinging", "story map failed", "tdd test not running", "api key exhausted", "fix-worker failed", "pdca not improving", or any mushi error/failure. |
Mushi Debug Guide
SDK Not Reporting Events
Symptoms: Inventory → Discovery shows 0 events.
- Check the SDK is initialized before any navigation:
Mushi.init({ projectId: '...', apiKey: '...', capture: { discoverInventory: { enabled: true } } })
- Verify the API key starts with
mushi_ and belongs to the correct project.
- Check browser console for
[Mushi] errors.
- Run
mushi doctor — confirms reachability.
API Key Exhausted / Rate Limited
Symptoms: "ALL_KEYS_EXHAUSTED" error, quota banner in Settings.
mushi keys list
mushi keys add --provider anthropic --key sk-ant-... --label "Backup"
In the console: Settings → API Key Pool → keys in quota_exhausted state show cooldown timer (resets in 1 hour automatically).
Story Mapping Failed
Symptoms: mushi stories map returns error or crawl run shows failed.
- Confirm Firecrawl key is configured:
mushi keys list
- Verify the URL is publicly reachable (not localhost).
- Check the console: Inventory → Discovery → Recent crawls for the error message.
- Try with fewer pages:
mushi stories map --url <url> --max-pages 5 --wait
QA Story Failing Hourly
Symptoms: Slack message every hour — :warning: QA story <name> errored — or Firecrawl 401.
Most common root causes and fixes:
| Error | Cause | Fix |
|---|
Firecrawl 401 Unauthorized: Token missing | No Firecrawl BYOK key in project | mushi integrations test firecrawl → if fails, add key: mushi keys add --provider firecrawl --key fc-... |
no_target_url: set a Target URL on this story | Story has no target_url and prompt doesn't contain a URL | Edit story in QA Coverage → Edit → Target URL |
| Link in Slack opens wrong page | Old story created before Jun 2026 deep-link fix | Links now go to /qa-coverage?story=<id>&run=<run-id> — verify admin console URL is correct |
mushi doctor --server --qa-stories
mushi qa runs <story-id>
mushi qa run <story-id>
Slack Not Receiving Notifications
Symptoms: No Slack message when a QA story fails or a report is classified.
mushi slack status
mushi slack test
If slack status shows "not connected":
- Go to Integrations → Slack → Add to Slack (OAuth flow)
- Select the channel and click Save
- Re-run
mushi slack test
If connected but no notifications for QA failures:
- Check Integrations → Notification Preferences —
qa_story.failed must be enabled
- Verify the story's
browser_provider is set (not null)
TDD Test Not Running
Symptoms: Generated test stays in pending_review, doesn't appear in QA schedule.
- Check approval status:
mushi tdd pending
- Approve the test:
mushi tdd approve <id>
- Verify
enabled=true in the console: QA Coverage page.
- Manual run:
mushi qa run <qa-story-id>
Edge Function Errors
Check Supabase logs via MCP:
Use the Supabase MCP: get_logs(service: 'edge-functions') to see function errors.
Or in Supabase dashboard: Functions → Logs → filter by function name.
Common edge function errors:
FIRECRAWL_API_KEY not set → Add key: mushi keys add --provider firecrawl --key fc-...
no_target_url: set a Target URL on this story → Edit story in QA Coverage and set Target URL
No accepted inventory → Accept a proposal in Inventory → Discovery first
story not found → The story id must match an id in the accepted inventory's user_stories[]
PDCA Improve Not Running
Symptoms: Failing tests not getting improved automatically.
- Check cron is registered:
SELECT * FROM cron.job WHERE jobname = 'pdca-qa-story-improve';
- Trigger manually:
mushi tdd improve
- Check that failing stories have
source='test_gen_from_story' and automation_mode IN ('auto', 'review').
Fix Worker Not Opening PRs
- Verify GitHub token is set in Settings → Integrations → GitHub.
- Confirm the repo URL matches exactly (with
.git stripped).
- Check
fix_attempts table for error messages.
MCP Tool Errors
MISSING_PROJECT: pass projectId argument explicitly
HTTP 403: API key lacks mcp:write scope — regenerate with correct scopes
HTTP 429: All keys exhausted — add backup keys