Mushi Debug Guide

SDK Not Reporting Events

Symptoms: Inventory → Discovery shows 0 events.

1. Check the SDK is initialized before any navigation:

   Mushi.init({ projectId: '...', apiKey: '...', capture: { discoverInventory: { enabled: true } } })

1. Verify the API key starts with mushi_ and belongs to the correct project.
2. Check browser console for [Mushi] errors.
3. Run mushi doctor — confirms reachability.

API Key Exhausted / Rate Limited

Symptoms: "ALL_KEYS_EXHAUSTED" error, quota banner in Settings.

# Check key health
mushi keys list

# Add a backup key
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.

1. Confirm Firecrawl key is configured:

   mushi keys list
   # Should show firecrawl [active]

1. Verify the URL is publicly reachable (not localhost).
2. Check the console: Inventory → Discovery → Recent crawls for the error message.
3. 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:

# Check all QA health in one command
mushi doctor --server --qa-stories

# See recent run errors
mushi qa runs <story-id>

# Manually trigger a run to verify the fix
mushi qa run <story-id>

Slack Not Receiving Notifications

Symptoms: No Slack message when a QA story fails or a report is classified.

# Check connection
mushi slack status

# Send test message
mushi slack test

If slack status shows "not connected":

1. Go to Integrations → Slack → Add to Slack (OAuth flow)
2. Select the channel and click Save
3. 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.

1. Check approval status:

   mushi tdd pending

1. Approve the test: mushi tdd approve <id>
2. Verify enabled=true in the console: QA Coverage page.
3. 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.

1. Check cron is registered:

   SELECT * FROM cron.job WHERE jobname = 'pdca-qa-story-improve';

1. Trigger manually:

   mushi tdd improve

1. Check that failing stories have source='test_gen_from_story' and automation_mode IN ('auto', 'review').

Fix Worker Not Opening PRs

1. Verify GitHub token is set in Settings → Integrations → GitHub.
2. Confirm the repo URL matches exactly (with .git stripped).
3. 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