> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

export const ThemedImage = ({light, dark, alt = ""}) => <>
    <img src={light} alt={alt} className="block dark:hidden" />
    <img src={dark ?? light} alt={alt} className="hidden dark:block" />
  </>;

# Troubleshooting

Solutions to common problems and issues with Overdeck.

## PR stuck with stale failed checks after main recovers

A pull request may remain `UNSTABLE` with a failed `test` check and
`ready_for_merge=0` even though its review, test, and verification stages passed
and `main` is green. `ready_for_merge=0` means the merge gate is deliberately
holding the pull request out of the merge queue because GitHub still reports a
required check failure.

This happens when the pull request's check ran while `main` was failing and
GitHub did not run it again after `main` recovered. The dashboard's stale-check
re-trigger service detects these inherited failures and re-runs them once. A
**red window** is the period from a completed failing run on `main` until the
next completed successful run of the same workflow. The service only acts on a
pull request run created inside a closed red window, never while that workflow
is still failing on `main`.

The service also requires the GitHub workflow run to have `attempt: 1`. This
once-only attempt guard means a run that Overdeck already retriggered, including
one that failed again, is not put into a retry loop. Decisions and actions are
logged with the `[stale-check-retrigger]` prefix.

If the dashboard is down, the run predates the available `main` history, or the
run is already on attempt 2 or later, re-run the failed jobs manually:

```bash theme={null}
gh run rerun <run-id> --failed
```

After GitHub reports the new result, the existing merge-blocker reconciliation
poll clears the stale blocker within about 10 minutes.

## Issue passed review but is missing from Awaiting Merge

The canonical review status may report `readyForMerge: true` while the issue is
missing from **Awaiting Merge** and merge actions remain disabled. This means a
`review.status_changed` event was lost, so the dashboard's event-driven read
model is stale even though the canonical record is correct.

The dashboard checks for this drift every 60 seconds and re-emits canonical
status automatically, so the issue normally repairs itself within one minute.
To recover immediately, open the issue action menu and choose **Recover →
Re-sync pipeline state**, or run:

```bash theme={null}
pan review resync <id>
```

Both recovery paths only re-emit the canonical status. They do not change the
review, test, verification, or merge verdict.

## WSL2 Stability Issues (Windows Users)

WSL2 can experience crashes and networking issues, especially under heavy AI agent workloads. Here are recommended `.wslconfig` settings to improve stability.

### Recommended Configuration

**Create/edit `C:\Users\<username>\.wslconfig`:**

```ini theme={null}
[wsl2]
# Resource allocation (adjust based on your system)
memory=40GB
processors=18
swap=8GB

# Localhost forwarding between Windows and WSL
localhostForwarding=true

# Disable GPU/GUI passthrough - reduces dxg driver errors
guiApplications=false

# ============================================================
# WINDOWS 11 ONLY - Comment these out on Windows 10!
# These settings require Windows 11 22H2 or later.
# On Windows 10 they are silently ignored or may cause issues.
# ============================================================

# Route DNS through Windows - prevents getaddrinfo() failures
# dnsTunneling=true          # Windows 11 only

# Inherit Windows proxy settings
# autoProxy=true             # Windows 11 only

# Aggressively reclaim cached memory
# autoMemoryReclaim=dropCache  # Windows 11 only

# Use sparse VHD to allow better memory compaction
# sparseVhd=true             # Windows 11 only

# Mirrored networking (may conflict with Docker Desktop)
# networkingMode=mirrored    # Windows 11 only
```

**After changing `.wslconfig`:**

```powershell theme={null}
wsl --shutdown
# Then relaunch your WSL terminal
```

**Verify settings applied:**

```bash theme={null}
# Check resources
free -h          # Should show configured memory
nproc            # Should show configured processors
swapon --show    # Should show configured swap

# Check networking mode (Windows 11 only)
ip addr show eth0  # NAT mode shows 172.x.x.x IP
                   # Mirrored mode shares Windows network directly
```

### Windows 10 Limitations

| Feature                        | Windows 10      | Windows 11 22H2+ |
| ------------------------------ | --------------- | ---------------- |
| `memory`, `processors`, `swap` | ✅ Works         | ✅ Works          |
| `localhostForwarding`          | ✅ Works         | ✅ Works          |
| `guiApplications=false`        | ✅ Works         | ✅ Works          |
| `networkingMode=mirrored`      | ❌ Not supported | ✅ Supported      |
| `dnsTunneling=true`            | ❌ Not supported | ✅ Supported      |
| `autoProxy=true`               | ❌ Not supported | ✅ Supported      |
| `autoMemoryReclaim`            | ❌ Not supported | ✅ Supported      |
| `sparseVhd=true`               | ❌ Not supported | ✅ Supported      |

**Windows 10 users:** Most advanced WSL2 features require Windows 11. On Windows 10, only the basic resource limits and `localhostForwarding`/`guiApplications` settings are supported. Other settings will be silently ignored or may cause instability.

If you experience frequent WSL2 crashes on Windows 10, consider:

* Using only the basic settings shown above (memory, processors, swap, localhostForwarding, guiApplications)
* Reducing `memory` allocation if system is under pressure
* Upgrading to Windows 11 for full WSL2 feature support
* Checking Windows Event Viewer for specific crash causes

### Additional Windows 10 Workarounds

If NAT networking is unstable on Windows 10:

```powershell theme={null}
# 1. Update WSL to latest version
wsl --update

# 2. Check for VPN/firewall conflicts
# Disable VPN temporarily to test if it's causing issues

# 3. Reset Windows network stack (run as Admin)
netsh winsock reset
netsh int ip reset

# 4. Restart after network reset
Restart-Computer
```

**Common conflict sources:**

* VPN clients (especially corporate VPNs)
* Docker Desktop (can conflict with WSL networking)
* Third-party firewalls
* Hyper-V virtual switch issues

**If NAT fails completely**, WSL 2.3.25+ automatically falls back to VirtioProxy mode. This is less performant but more stable. You'll see: `"Failed to configure network (networkingMode Nat), falling back to networkingMode VirtioProxy."`

**References:**

* [Microsoft WSL Networking Documentation](https://learn.microsoft.com/en-us/windows/wsl/networking)
* [WSL GitHub Issues - Networking](https://github.com/microsoft/WSL/issues?q=networking+mirrored)
* [WSL NAT Fallback Issue #12297](https://github.com/microsoft/WSL/issues/12297)

## Slow Vite/React Frontend with Multiple Workspaces

If running multiple containerized workspaces with Vite/React frontends, you may notice CPU spikes and slow HMR. This is because Vite's default file watching polls every 100ms, which compounds with multiple instances.

**Fix:** Increase the polling interval in your `vite.config.mjs`:

```javascript theme={null}
server: {
    watch: {
        usePolling: true,
        interval: 3000,  // Poll every 3s instead of 100ms default
    },
}
```

A 3000ms interval supports 4-5 concurrent workspaces comfortably while maintaining acceptable HMR responsiveness.

## Dev server dies with ENOSPC — inotify watch exhaustion

If a workspace's frontend container crash-loops at startup with `ENOSPC: System limit for number of file watchers reached` while the rest of the host looks healthy, the per-user inotify watch budget (`fs.inotify.max_user_watches`) is exhausted. This budget is a kernel limit shared by **every process and container the user runs** — Docker does not isolate it — so a few heavy file watchers can starve every other workspace on the machine.

The dashboard shows a **File watchers running low / exhausted** banner when usage crosses 80% / 90% of the limit, and `pan doctor` reports usage, the top consumers, and whether the configured limit survives a reboot.

**Fix, in order of leverage:**

1. **Shrink the watchers.** The usual culprit is a huge directory inside the watched project root that the watcher does not ignore by default — e.g. pnpm's `.pnpm-store/` (pnpm places it inside the project when installing into a Docker bind mount, and Vite ignores `node_modules` but not `.pnpm-store`). Add it to the watch ignore list:

   ```javascript theme={null}
   server: {
       watch: {
           ignored: ['**/node_modules/**', '**/.git/**', '**/.pnpm-store/**'],
       },
   }
   ```

   In one real incident this cut each dev server from \~157k watches to \~13k — a 12× reduction.

2. **Raise and persist the limit** (requires sudo; Overdeck never runs sudo itself):

   ```bash theme={null}
   echo 'fs.inotify.max_user_watches = 2097152' | sudo tee /etc/sysctl.d/99-inotify.conf
   sudo sysctl --system
   ```

   A `sysctl -w` alone does not survive a reboot; the `/etc/sysctl.d` file does. `pan doctor` warns when the live limit is higher than anything persisted.

## Corrupted Workspaces

A workspace can become "corrupted" when it exists as a directory but is no longer a valid git worktree. The dashboard will show a yellow "Workspace Corrupted" warning with an option to clean and recreate.

### Symptoms

* Dashboard shows "Workspace Corrupted" warning
* `git status` in the workspace fails with "not a git repository"
* The `.git` file is missing from the workspace directory

### Common Causes

| Cause                       | Description                                                             |
| --------------------------- | ----------------------------------------------------------------------- |
| **Interrupted creation**    | `pan workspace create` was killed mid-execution (Ctrl+C, system crash)  |
| **Manual .git deletion**    | Someone accidentally deleted the `.git` file in the workspace           |
| **Disk space issues**       | Ran out of disk space during workspace creation                         |
| **Git worktree pruning**    | Running `git worktree prune` in the main repo removed the worktree link |
| **Force-deleted main repo** | The main repository was moved or deleted while workspaces existed       |

### Resolution

**Via Dashboard (recommended):**

1. Click on the issue to open the detail panel
2. Click "Clean & Recreate" button
3. Review the files that will be deleted
4. Check "Create backup" to preserve your work (recommended)
5. Click "Backup & Recreate"

**Via CLI:**

```bash theme={null}
# Option 1: Manual cleanup
rm -rf /path/to/project/workspaces/feature-issue-123
pan workspace create ISSUE-123

# Option 2: Backup first
cp -r /path/to/project/workspaces/feature-issue-123 /tmp/backup-issue-123
rm -rf /path/to/project/workspaces/feature-issue-123
pan workspace create ISSUE-123
# Then manually restore files from backup
```

### Prevention

* Don't interrupt `pan workspace create` commands
* Don't run `git worktree prune` in the main repo without checking for active workspaces
* Ensure adequate disk space before creating workspaces

## Docker Issues

### Container won't start

```bash theme={null}
# Check container logs
docker logs <container-name>

# Common issues:
# - Port already in use
# - Volume mount permissions
# - Missing environment variables
```

### "No such network: overdeck"

```bash theme={null}
# Create the network
docker network create overdeck
```

### Permission denied on mounted volumes

If containers run as root and create files, you won't be able to delete them:

```bash theme={null}
# Use sudo to remove
sudo rm -rf /path/to/workspace

# Or run container as your user
# In docker-compose.yml:
services:
  app:
    user: "${UID}:${GID}"
```

## Network Issues

### HTTPS not working

1. Check certificates exist:
   ```bash theme={null}
   ls ~/.overdeck/traefik/certs/
   ```

2. Regenerate if missing:
   ```bash theme={null}
   cd ~/.overdeck/traefik/certs
   mkcert localhost "*.localhost" 127.0.0.1 ::1
   ```

3. Install the CA:
   ```bash theme={null}
   mkcert -install
   ```

### Can't reach workspace URLs

1. Check Traefik is running:
   ```bash theme={null}
   docker ps | grep traefik
   ```

2. Check DNS resolution:
   ```bash theme={null}
   ping feature-min-123.localhost
   ```

3. Check Traefik dashboard ([http://localhost:8080](http://localhost:8080)) for routing rules

## Agent Issues

### Agent stuck / not responding

```bash theme={null}
# Check tmux session
tmux capture-pane -t agent-min-123 -p

# Kill and restart
pan work kill MIN-123
pan work issue MIN-123
```

### Agent keeps failing

Check the handoff count in state.json. If it's high, the task may be too complex:

```bash theme={null}
cat ~/.overdeck/agents/agent-min-123/state.json | jq .handoffCount
```

Consider:

* Breaking the issue into smaller tasks
* Adding more context to the issue description
* Manually handling complex parts

### Messages not reaching agent

Use the proper messaging API:

```bash theme={null}
# Correct
pan work tell MIN-123 "Your message"

# NOT this (won't send without Enter)
tmux send-keys -t agent-min-123 "Your message"
```

## Command Deck Issues

### Command Deck shows "Unknown project"

A URL such as `/command-deck/<slug>` shows an **Unknown project** state when
`<slug>` matches neither a registered project key nor its display name. This
usually means the URL is stale, the project was renamed, or the project is not
registered on this machine. The page does not open a functional project deck
for that slug.

Use the registered-project buttons in the recovery panel to navigate to a valid
deck, or select **Back to Command Deck** to return to `/command-deck`. To inspect
the registered keys from the CLI, run:

```bash theme={null}
pan projects list
```

### Conversation creation fails from a launcher

When a launcher cannot create a conversation, the failure appears inline beside
the composer and the typed query remains available for correction or retry. The
launcher blocks duplicate keyboard and pointer submissions while creation is in
progress, and it opens a conversation pane only after the server reports a
successful creation.

If the inline error reports an unknown project, use the recovery steps above to
open a registered project deck before retrying.

## Workspace Issues

### Workspace creation fails

```bash theme={null}
# Check for existing workspace
ls /path/to/project/workspaces/feature-min-123

# Check git worktree status
cd /path/to/project
git worktree list

# Clean up orphaned worktrees
git worktree prune
```

### Can't delete workspace

If containers created root-owned files:

```bash theme={null}
# Via Overdeck (handles Docker cleanup)
pan workspace destroy MIN-123

# Manual with sudo
sudo rm -rf /path/to/workspace
```

## Performance Issues

### Dashboard slow to load

```bash theme={null}
# Restart the dashboard
pan restart

# Or kill and restart
pan down
pan up
```

### High CPU usage

* Check number of concurrent workspaces
* Increase Vite polling interval (see above)
* Run `docker stats` to identify resource-heavy containers

### High memory usage

```bash theme={null}
# Check Docker memory
docker stats

# Prune unused containers/images
docker system prune -a
```

## Getting Help

### Health page

The dashboard's **Health** page reports live host, admission, agent, and
optional-service health. Use it when the running fleet looks unhealthy: it
shows current pressure evidence, spawn headroom, agent/session state, and
service state without turning unavailable measurements into zeroes.

<ThemedImage light="/images/dashboard/health-light.png" dark="/images/dashboard/health-dark.png" alt="Overdeck Health page showing system health checks and diagnostics" />

<Tip>
  These surfaces answer different questions. `pan health` reports runtime health
  of Overdeck services, while `pan doctor` checks dependencies, installation,
  configuration, and broader system diagnostics. They overlap, but neither CLI
  command is a textual equivalent of the live Health page.
</Tip>

### Diagnostic Information

When reporting issues, include:

```bash theme={null}
# System info
pan doctor

# Current state
pan status

# Recent logs
tail -50 ~/.overdeck/logs/*.log
```

### Resources

* **GitHub Issues:** [https://github.com/eltmon/overdeck/issues](https://github.com/eltmon/overdeck/issues)
* **Documentation:** [https://docs.overdeck.ai](https://docs.overdeck.ai)
* **CLI Help:** `pan --help` or `pan <command> --help`

## Related Guides

* [Docker & HTTPS Setup](/guides/docker-setup) - Network configuration
* [Architecture](/reference/architecture) - System internals
* [Core Commands](/cli/core-commands) - CLI reference