Troubleshooting

Most Crew problems have a fix that fits in a shell command. This page is a triage guide. Start with a health check:

kirocrew doctor

doctor reports the status of every subsystem: kiro-cli binary discovery, agent authentication, embedding model, Slack tokens, config validity, and MCP server probes. If it flags an issue, jump to the matching section below.

The install target directory isn't on your PATH. Fixes depend on the installer:

• Prebuilt wheel installer — uses pipx when available, else ~/.kiro/crew/venv. Ensure ~/.local/bin (pipx default) or ~/.kiro/crew/venv/bin is on PATH.
• pip install -e . — ensure your Python's script directory is on PATH. Typically ~/.local/bin (user install) or the venv's bin/.
• Docker — call via docker exec kirocrew kirocrew ….

Then source ~/.bashrc (or restart your shell).

On Windows use python and py from a venv:

py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -e . tzdata
python -m kiro_crew gateway

tzdata is required — Windows ships no IANA zone database, so zoneinfo.ZoneInfo(...) fails without it.

The entrypoint probed the inner Linux user-namespace sandbox and it failed under the container runtime's seccomp/AppArmor policy. Two options:

1. Permit user namespaces — restart with --security-opt seccomp=<profile permitting unshare/clone>. The gateway probes again on next start and enables the sandbox.
2. Accept unsandboxed exec — restart with -e KIROCREW_ALLOW_UNSANDBOXED=1. Agent commands run without the inner sandbox; the container remains the only isolation boundary.

Log output on start states which posture was chosen.

The agent backend didn't respond to the handshake. Common causes:

1. kiro-cli not installed — the dashboard Set up Kiro page walks you through it, or kirocrew doctor reports missing binary
2. Not logged in — run kiro-cli login
3. Broken MCP config — kirocrew setup --agent-only --clean rebuilds the agent from scratch
4. First launch is slow — MCP server initialization can take 60+ seconds; wait it out

The kiro-cli process crashed. Crew auto-recovers by recreating the session and retrying. If it repeats:

• Check kirocrew logs -f for the underlying error
• If OOM-killed, reduce concurrent subagents (agent.max_subagents) or increase host memory
• Circuit breaker trips after 5 consecutive failures and auto-resets — usually recovers on its own

The active project directory isn't set. Check with kirocrew config get project_dir, or set it in the dashboard's session header.

If the CWD is set but the agent still can't read a specific path, check the OS sandbox — some paths are hidden in auto and strict modes.

1. Check the embedding model status: kirocrew doctor reports whether the bundled runtime downloaded the model
2. First-run downloads happen in the background (~610MB). Wait a few minutes and re-check.
3. Set a mirror URL if the CDN is unreachable: export KIROCREW_EMBED_MODEL_URL=<url>
4. Fall back to Ollama if preferred: ollama pull qwen3-embedding:0.6b and check curl http://localhost:11434/api/tags

Until the model lands, memory falls back to keyword search (LIKE on text + tags). The agent still runs — just without semantic ranking.

The restored memory.db is corrupted. Usually a copy-paste issue (interrupted transfer). Try:

kirocrew restore snapshot.tar.gz --mode replace --dry-run    # preview
kirocrew restore snapshot.tar.gz --mode replace --components memory

If it still fails, the snapshot itself is bad. Restore from an older snapshot or manually import memory.db from another source.

• Incognito mode is on — check the session header for the incognito indicator. Incognito sessions never write memory.
• Consolidator not running — memory consolidation triggers at 30 messages (prefs path) or 3h idle (history path). A short session may not reach either trigger.
• Disk full — df -h ~/.kiro/crew; SQLite silently fails on write when the disk fills

Slack is optional — the dashboard works without it. If you want Slack:

1. Verify tokens are set: cat ~/.kiro/crew/.env should show SLACK_APP_TOKEN=xapp-…, SLACK_BOT_TOKEN=xoxb-…, KIROCREW_OWNER_ID=U0…
2. Confirm Socket Mode is enabled in your Slack app settings
3. Re-run kirocrew setup — the wizard prompts for both tokens
4. kirocrew doctor reports Slack connect status

• Owner lock — the Slack gateway is locked to KIROCREW_OWNER_ID. Only your Slack Member ID can DM the bot. Non-owner messages are silently dropped.
• Enterprise Grid — if slack.allowed_enterprise_ids is set, messages from other workspaces are dropped
• Bot offline — check kirocrew logs -f for websocket disconnect errors

You added a new feature that needs a scope not granted at install time. Fix:

1. In the Slack app settings, add the missing scope under OAuth & Permissions → Bot Token Scopes
2. Reinstall the app to your workspace (Install to Workspace button)
3. Re-run kirocrew setup — paste the new bot token

Add app_home_opened event, enable Home Tab in Slack app settings, reinstall the app.

Known Slack UI bug. Use Features → OAuth & Permissions → Install to Workspace instead — it does the same thing.

1. Confirm DISCORD_BOT_TOKEN is set and kirocrew doctor reports Discord connected
2. Verify the user is in discord.allowed_users (deny-by-default allowlist)

Add the user's Discord ID to discord.allowed_users via config or the dashboard's Discord settings panel.

Discord caps messages at 2000 characters. The transport splits automatically. If you see truncation instead of a split, check for a fragile custom formatter.

1. Check ~/.kiro/agents/kirocrew.json has kirocrew-core and kirocrew-cron
2. Verify includeMcpJson: false is set
3. Run kirocrew doctor — it reports MCP probe status
4. Dashboard → Integrations (MCP) panel shows live probe results

Nukes and rebuilds MCP config from scratch. Solves most "broken MCP" issues.

The gateway auto-triggers a probe when a new server appears, but results only surface on the next dashboard refresh. Wait a few seconds and reload. If it stays "Unknown", the server is failing to handshake — check the error text or kirocrew logs -f.

Correct behavior. kirocrew-core and kirocrew-cron are agent-scoped and should not appear in interactive kiro-cli sessions. If they do, something wrote them to a provider global — file a bug.

Check the Crew badge on the row. When it stays green, the preservation rule copies the server's config into ~/.kiro/crew/mcp.json before removing it from the global, so it keeps loading in Crew sessions.

Toggle the Crew badge off before removing from the global to fully remove.

Session reset drains the warm pool. Use Dashboard → Apply & Restart, or run kirocrew config set (which auto-triggers a restart).

• Token expired — mint a new one: kirocrew token --ttl 2h
• IP changed — dashboard tokens are IP-pinned on first use; if your IP changed, mint a new token
• Remote access without token — you can't hit the dashboard remotely without a valid token; the three exceptions are health probes, static assets, and loopback-only bootstrap

The bundled runtime downloads its model over HTTPS from the Crew CDN on gateway startup. Check:

• Network reachability to the CDN
• Disk space in ~/.kiro/crew/models/
• Set KIROCREW_EMBED_MODEL_URL to a mirror if the default CDN is unreachable

Until the model lands, memory works with keyword search.

• Cold session pool — the first message on a new tab has a 3–5s cold-start penalty. Increase session.pool_size (default 1) if you have RAM to spare.
• Warmup burst — Docker containers with many MCP servers can take 60+ seconds on first start

The gateway is still initializing. Common causes:

• MCP servers finishing initial probes
• Warm session pool spawning
• Embedding model download in progress

Wait 30 seconds, then refresh. Persistent → check kirocrew logs -f.

kirocrew doctor              # diagnose
kirocrew gateway --port auto # try a random port if 5476 is in use

If port 5476 is in use:

lsof -iTCP:5476 -sTCP:LISTEN    # find what's on it

• Circuit breaker — 5 consecutive failures auto-reset; usually recovers on its own
• Force reset — from the dashboard, delete the slot and start a new one
• Kill everything — kirocrew restart

Session context is filling too fast. Options:

• Reduce injected context: skills.lazy_load: true for stricter budgeting
• Increase compact threshold: session.autocompact_pct: 95
• Use incognito mode for sensitive high-volume conversations

Watchdog fires at 60 min (warn) and 2 h (reset). If the task is genuinely stuck:

• Check kirocrew logs -f for the specific step's session activity
• Cancel and restart from a specific step: POST /api/taskrunner/{task_id}/retry with from_step: N

• TEST_TIMEOUT is 90 min per test run; if your test suite takes longer, override with a per-step config or split the task
• Run tests manually with kirocrew run TASK.md --no-test to see what the agent produces before the test gate

The task retried the same failing step 3 times with identical errors. The task runner marks the step FAILED to avoid burning through retries on an impossible fix.

Debug: check the step's error message. Common causes:

• The step's acceptance criterion is unachievable given the current codebase
• A dependency is missing (agent can't install it either)
• The reviewer is rejecting for a reason unrelated to correctness

Consider marking the step requires_approval: true and inspecting the state manually.

Check spawn list for status. If it shows stalled (no activity in 120s), the subagent is idle — either legitimately (waiting on approval) or stuck.

• Blocked on approval — check the dashboard for a pending approval prompt
• Stuck — use spawn cancel <id> from the dashboard row Stop button

The reaper force-reaps at the 30-minute hard timeout.

The subagent may have failed at spawn (empty task, low memory, cwd rejected, governance denial). Check spawn list for a terminal failed state with the reason.

• Gateway was down — the scheduler doesn't catch up on restart
• Job is paused — kirocrew cron list shows status
• --no-crons was passed to gateway — the scheduler is disabled

Check the delivery routing:

• Default: Slack DM if configured, else dashboard notification
• With <!-- deliver:C0123CHANNEL --> marker: routes to that Slack channel
• With --silent: no notification unless the agent explicitly sends one

• kirocrew config set — auto-triggers a session pool restart. Should work.
• Env var change — requires kirocrew restart
• File hand-edit — you can also kirocrew restart to force a reload

You set a numeric config value outside the allowed range. It was clamped to the boundary; the SEL entry records the clamp. Adjust your value or check the Configuration reference for the valid ranges.

WAL checkpoint failed because the gateway holds a lock. The snapshot still proceeds — SQLite's backup() API produces a consistent copy including committed WAL data. The warning is informational.

Snapshots reject symlinks and hardlinks for security. If your snapshot contains one (unusual), the archive is malformed. Regenerate the snapshot from a clean source.

Set instances.enabled: true in ~/.kiro/crew/config.json and restart the gateway.

The CSP frame-src relaxation only applies to active tunnel ports. Confirm the instance is connected (Manage panel shows a green connected badge), not just added.

Refresh SSH credentials (re-add key to ssh-agent). Tunnels self-heal once SSH is restored.

Health probe + 2-tier self-heal retries over ~2 min (8 attempts, capped exponential backoff). If it gives up, diagnosis runs automatically. Check:

• The remote gateway is actually running (ssh <host> kirocrew doctor)
• SSH stability from the hub to the remote
• Time drift — tokens are time-signed; large clock skew causes rejection

Grant the browser microphone permission for the dashboard origin. In Chrome: address bar padlock → Site settings → Microphone → Allow.

• Check the dashboard tab's audio permission (browser padlock)
• Confirm system output isn't muted
• First-use Piper voice download may not have finished yet; check network + ~/.kiro/crew/voices/

• Try a quieter room
• Switch to aws_transcribe for cloud-grade accuracy: pip install "kirocrew[voice]", then set voice.stt_provider: "aws_transcribe" and configure AWS credentials

The reaper stack is missing for that profile / region. Two options:

• Run install-reaper.sh --profile <name> --region <region>
• Use ttl_hours: 0 (persistent, no reaper needed)

The deployed site's headers pre-date the current base stack. Any subsequent deploy updates the stack in place. Until then, the card shows the status fallback with a plain link — click through to see the site.

If nothing here fits your issue:

• Verbose logs — kirocrew logs -f (live tail), kirocrew doctor --verbose
• File a bug — github.com/kirodotdev/KiroCrew/issues
• Check the source — every subsystem is documented under docs/system-specs/modules/ in the Crew repo