Troubleshooting Guide

Overview

This skill helps diagnose and fix common issues with Overdeck installation, configuration, and operation.

Issue Categories

1. Installation Issues
2. Configuration Issues
3. Agent Issues
4. Dashboard Issues
5. Skill Issues
6. Network Issues

---

Installation Issues

"pan: command not found"

# Check if installed
npm list -g overdeck

# Install globally
npm install -g overdeck

# Or use npx
npx overdeck doctor

# Check PATH
echo $PATH | tr ':' '\n' | grep npm

"Cannot find module" errors

# Reinstall dependencies
npm install -g overdeck --force

# Clear npm cache if needed
npm cache clean --force
npm install -g overdeck

Node.js version issues

# Check version
node --version

# Need Node 18+
# Use nvm to switch
nvm install 18
nvm use 18

---

Configuration Issues

"LINEAR_API_KEY not found"

# Check config file exists
cat ~/.overdeck.env

# Create/update config
echo "LINEAR_API_KEY=lin_api_xxx" >> ~/.overdeck.env

# Verify
grep LINEAR_API_KEY ~/.overdeck.env

"Invalid Linear API key"

# Test the key
curl -H "Authorization: lin_api_xxx" \
  https://api.linear.app/graphql \
  -d '{"query": "{ viewer { id } }"}'

# Get a new key from: Linear > Settings > API > Personal API Keys

"GitHub token invalid"

# Test the token
curl -H "Authorization: token ghp_xxx" \
  https://api.github.com/user

# Create new token: GitHub > Settings > Developer settings > Personal access tokens
# Required scopes: repo, read:org

Config file permissions

# Fix permissions (should be readable only by owner)
chmod 600 ~/.overdeck.env

---

Agent Issues

Agent won't start

# Check tmux is available
which tmux
tmux -V

# Try starting manually
tmux new-session -d -s test-agent "echo 'test'; sleep 5"
tmux capture-pane -t test-agent -p
tmux kill-session -t test-agent

# Check for existing session
tmux list-sessions | grep agent-ISSUE

Agent is stuck

# Check what it's doing
tmux capture-pane -t agent-ISSUE-123 -p | tail -50

# Look for:
# - API rate limits
# - Waiting for user input
# - Long-running commands
# - Error messages

# Try sending a message (ALWAYS use pan tell, NOT raw tmux)
pan tell ISSUE-123 "What is your current status?"

WARNING: DO NOT use raw tmux send-keys - agents often forget the Enter key. Always use pan tell which handles this correctly.

OpenCode conversation stuck after a permission ask

An OpenCode Task subagent can block its parent turn if its permission request
does not reach ACP. First check whether the host watchdog already recovered it:

CONVERSATION=conv-YYYYMMDD-NNNN
grep '"source":"watchdog"' \
  "$HOME/.overdeck/agents/$CONVERSATION/acp-session.jsonl" | tail -5

If the turn is still stuck, list the pending asks on the host's recorded port,
then reply to the relevant permission id:

OPENCODE_PORT=$(cat "$HOME/.overdeck/agents/$CONVERSATION/opencode-port")
curl -sS "http://127.0.0.1:$OPENCODE_PORT/permission"
curl -sS -X POST \
  "http://127.0.0.1:$OPENCODE_PORT/permission/<permission-id>/reply" \
  -H 'content-type: application/json' \
  -d '{"reply":"always"}'

If opencode-port is absent, the conversation predates the watchdog. Use
ss -ltnp to find the loopback port owned by its opencode acp process.

Agent crashed

# Check if session exists
tmux has-session -t agent-ISSUE-123 2>/dev/null && echo "Running" || echo "Not running"

# If dead, check workspace for clues
cd /path/to/workspaces/ISSUE-123
cat .pan/context.md
cat .pan/continue.json

# Resume with new agent
pan start ISSUE-123

Multiple agents for same issue

# List all
tmux list-sessions | grep ISSUE-123

# Kill duplicates
tmux kill-session -t agent-ISSUE-123-old

---

Dashboard Issues

Dashboard won't start

# Check port availability
lsof -i :3010  # Frontend
lsof -i :3011  # Backend API

# Kill processes using ports
kill $(lsof -t -i:3010) 2>/dev/null
kill $(lsof -t -i:3011) 2>/dev/null

# Start fresh
cd ~/.overdeck/dashboard
npm run dev

"CORS error" in browser

# Check API is running
curl http://localhost:3011/api/health

# Check frontend is pointing to correct API
# Should be http://localhost:3011

# Try different browser or incognito mode

Dashboard shows stale data

# Restart the API server
pkill -f "node.*dashboard.*server"
cd ~/.overdeck/dashboard/server && npm run dev

# Hard refresh browser
# Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)

WebSocket not connecting

# Check server logs
cd ~/.overdeck/dashboard/server
npm run dev 2>&1 | grep -i websocket

# Check firewall
sudo ufw status

---

Skill Issues

Skills not showing up

# Check sync status
pan skills

# Re-sync
pan sync --force

# Verify symlinks
ls -la ~/.claude/skills/ | grep overdeck

# Check Claude Code recognizes them
# Restart Claude Code after syncing

"Skill already exists"

# Check what's there
ls -la ~/.claude/skills/skill-name

# If it's a project skill, symlink won't be created (by design)
# If you want to override, remove the project skill first

Skill not triggering

# Check trigger patterns in SKILL.md
cat ~/.overdeck/skills/skill-name/SKILL.md | head -20

# Ensure you're using exact trigger phrases
# Try: /skill-name instead of natural language

---

Network Issues

Can't reach Linear API

# Test connectivity
curl -v https://api.linear.app/graphql

# Check DNS
nslookup api.linear.app

# Check proxy settings
echo $HTTP_PROXY $HTTPS_PROXY

Traefik not routing

# Check Traefik is running
docker ps | grep traefik

# Check Traefik logs
docker logs traefik

# Verify DNS resolution
ping myapp.overdeck.localhost

# Check /etc/hosts
grep overdeck.localhost /etc/hosts

WSL2 networking

# Get WSL2 IP
hostname -I

# Check Windows can reach WSL2
# From Windows: ping <wsl-ip>

# Port forwarding (from Windows PowerShell as Admin)
netsh interface portproxy show all

---

Collecting Diagnostics

For bug reports, collect:

# System info
echo "=== System ===" > diagnostics.txt
uname -a >> diagnostics.txt
node --version >> diagnostics.txt
npm --version >> diagnostics.txt

# Config (redact secrets!)
echo "=== Config ===" >> diagnostics.txt
cat ~/.overdeck.env | sed 's/=.*/=REDACTED/' >> diagnostics.txt

# Status
echo "=== Doctor ===" >> diagnostics.txt
pan doctor >> diagnostics.txt 2>&1

# tmux
echo "=== tmux ===" >> diagnostics.txt
tmux list-sessions >> diagnostics.txt 2>&1

# Skills
echo "=== Skills ===" >> diagnostics.txt
ls -la ~/.overdeck/skills/ >> diagnostics.txt
ls -la ~/.claude/skills/ >> diagnostics.txt

cat diagnostics.txt

Related Skills

• /pan:health - Quick health check
• /pan:install - Reinstallation
• /pan:setup - Configuration