Command Palette

Search conversations, projects, playbooks, and more

Troubleshooting

Common issues and how to fix them.

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:

Configuration

Configure crewkit with environment variables, config files, and CI/CD settings.

FAQ

Frequently asked questions about crewkit

On this page

Authentication expiredProject not detectedNetwork errorsResource sync conflictsHook errorsObserver setup failedTerminal display issuesDebug logsGetting help
curl https://api.crewkit.io/api/v1/health
  • 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"