---
source: CrewKit documentation
url: https://crewkit.io/docs/troubleshooting.md
title: "Troubleshooting"
description: "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:

```bash
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:**

```bash
# 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:

```bash
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:

```bash
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:

```bash
# 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](https://github.com/karibew/crewkit-cli/issues) — `crewkit feedback "description of issue"`