Troubleshooting

Solutions to common problems you might hit when using crewkit.

Authentication expired

Symptom: 401 Unauthorized errors, or crewkit prompts you to log in again.

Fix: Access tokens expire after 4 hours. crewkit refreshes them automatically during active sessions. If you've been away:

crewkit auth login

Project not detected

Symptom: crewkit can't determine which project this repo belongs to.

Cause: Usually happens when:

• The git remote doesn't match any linked repository
• You're in a directory without a .git folder
• The organization doesn't have this repo linked

Fix:

# Initialize the project link
crewkit init

# Or let crewkit code handle it inline
crewkit code

Network errors

Symptom: Connection timeouts or DNS resolution failures.

Fix:

1. Check your internet connection
2. Verify the API is reachable: curl https://api.crewkit.io/api/v1/health
3. If behind a proxy, ensure HTTPS_PROXY is set

crewkit degrades gracefully on network failure — you can still use Claude Code, just without session tracking.

Resource sync conflicts

Symptom: Warning about locally modified files during sync.

Cause: You edited a file in .claude/ that crewkit also manages (agents, skills, rules, commands).

Fix: crewkit won't overwrite your local changes. It backs up your version to .claude/.backups/ and writes the synced version. To keep your changes:

1. Check .claude/.backups/ for your version
2. Merge your changes with the synced version
3. Use crewkit resources import to push local changes to the platform

Hook errors

Symptom: Hook handler errors in the debug log.

Fix: Check the debug log for details:

tail -50 .crewkit/debug-latest.log | grep -i hook

Common causes:

• The hook server port is already in use (rare — crewkit uses ephemeral ports)
• Claude Code version mismatch (update Claude Code)
• Malformed event data (usually resolved by restarting the session)

Observer setup failed

Symptom: The launch fails with cannot set up the background observer: ... instead of starting a session.

Cause: The background observer could not start (for example, the runtime directory could not be created). The launch fails with the reason rather than silently starting an unobserved session.

Fix: Fix the named cause — or run crewkit tui for the interactive terminal interface. Check the debug log for details:

tail -50 .crewkit/debug-latest.log

Terminal display issues

Symptom: Garbled output, missing characters, or layout problems in crewkit's interactive terminal interface (crewkit tui).

Fix:

• Try crewkit --plain tui for ASCII-only mode
• Ensure your terminal supports 256 colors
• Resize your terminal to at least 80x24
• If using tmux, ensure set -g default-terminal "screen-256color" is in your config

Debug logs

When reporting issues, include the debug log:

# Enable debug mode
crewkit code --debug

# Logs are at:
.crewkit/debug-latest.log

The debug log includes timing information, API request/response details, and hook event data. Sensitive information (tokens, credentials) is never logged.

Getting help

• Send feedback — crewkit feedback "description of issue"