Common Issues¶

Symptoms: Cub fails to start with an error mentioning jq.

Cause: jq is a required dependency for JSON processing but isn't installed.

Solution: Install jq for your platform:

brew install jq

sudo apt-get install jq

sudo dnf install jq

choco install jq
# Or download from jqlang.github.io/jq/download/

Verify installation:

jq --version

Symptoms: You get a permission error when trying to run cub or cub-init.

Cause: The script files don't have execute permissions.

Solution: Make the scripts executable:

chmod +x cub cub-init

If using symlinks in /usr/local/bin/, ensure the target files are executable:

chmod +x ~/tools/cub/cub ~/tools/cub/cub-init

Symptoms: You've installed Cub but can't run it from the command line.

Cause: Cub isn't in your PATH.

Solution: Choose one of these options:

export PATH="$PATH:$HOME/tools/cub"

source ~/.bashrc  # or ~/.zshrc

sudo ln -s $HOME/tools/cub/cub /usr/local/bin/cub
sudo ln -s $HOME/tools/cub/cub-init /usr/local/bin/cub-init

Verify Cub is accessible:

cub --version

Symptoms: Cub exits with an error about Bash version.

Cause: Your system has an older version of Bash.

Solution: Check your Bash version:

bash --version

On macOS (which ships with older Bash due to licensing):

# Install newer Bash
brew install bash

# Optionally set as default shell
sudo chsh -s /usr/local/bin/bash $USER

Symptoms: Cub starts but can't find an AI harness to use.

Cause: No AI coding CLI is installed on your system.

Solution: Install at least one harness:

npm install -g @anthropic-ai/claude-code

npm install -g openai-codex-cli

npm install -g @google/gemini-cli

npm install -g opencode

Verify installation:

which claude codex gemini-cli opencode

Symptoms: Cub can't find a specific harness you've configured.

Cause: The configured harness isn't installed or not in PATH.

Solution:

1. Diagnose with doctor:

   cub doctor
   

   This shows which harnesses are installed and which are missing.

2. Install the missing harness (see options above)

3. Or change the configured harness in .cub.json:

   {
     "harness": {
       "priority": ["codex", "claude"]
     }
   }
   

4. Or use a different harness at runtime:

   cub run --harness codex
   

Symptoms: Cub starts but the harness doesn't respond or fails.

Cause: Various - authentication, network, or rate limiting issues.

Solution:

Enable debug logging to see what's happening:

cub run --debug

Common causes and fixes:

# Test connectivity
curl -I https://api.anthropic.com

# Run single iterations with breaks
cub run --once
# Wait a bit between iterations

Symptoms: Cub fails with an error about task file format.

Cause: Your prd.json doesn't have the required structure.

Solution: Ensure your prd.json has a tasks array:

{
  "tasks": [
    {
      "id": "task-1",
      "title": "First task",
      "description": "What to do",
      "status": "open"
    }
  ]
}

Complete task structure:

{
  "id": "task-1",
  "title": "Task title",
  "description": "Detailed description",
  "status": "open",              // open, in_progress, completed, blocked
  "priority": 2,                 // 0-4 (0=critical, 4=backlog)
  "epic": "epic-id",             // optional
  "labels": ["label1"],          // optional
  "dependencies": [],            // optional
  "acceptance_criteria": []      // optional
}

Symptoms: Error about duplicate IDs in your task file.

Cause: Multiple tasks have the same id value.

Solution: Find and fix duplicates:

# Find duplicate IDs
jq '.tasks | group_by(.id) | map(select(length > 1)) | .[].id' prd.json

Then edit prd.json to make each ID unique.

Symptoms: Error about tasks referencing non-existent dependencies.

Cause: A task's dependencies array references an ID that doesn't exist.

Solution: Verify all dependency IDs exist:

# List all task IDs
jq '.tasks[].id' prd.json

# Show tasks with dependencies
jq '.tasks[] | select(.dependencies) | {id, dependencies}' prd.json

Ensure all referenced IDs exist and match exactly (case-sensitive).

Symptoms: Cub can't find or read your task file.

Solution:

1. Verify file exists:

   ls -la prd.json
   

2. If missing, initialize a project:

   cub init
   

3. If permission denied, fix permissions:

   chmod 644 prd.json
   

Symptoms: After configuring beads backend, you get errors about beads not being installed.

Cause: The Beads CLI isn't installed on your system.

Solution: Install Beads:

npm install -g @steveyegge/beads

Verify installation:

bd --version

Symptoms: Using beads backend but the .beads/ directory doesn't exist.

Cause: Beads hasn't been initialized in the project.

Solution: Initialize beads:

bd init

This creates:

• .beads/ directory
• .beads/issues.jsonl task database
• .beads/.gitignore to exclude internal files

Symptoms: Beads can't parse the task database.

Cause: The .beads/issues.jsonl file has invalid JSON.

Solution:

1. Diagnose the issue:

   # Validate JSON lines format
   cat .beads/issues.jsonl | while read line; do
     echo "$line" | jq . > /dev/null 2>&1 || echo "Invalid: $line"
   done
   

2. Backup and reinitialize (may lose data):

   cp .beads/issues.jsonl .beads/issues.jsonl.bak
   rm -rf .beads
   bd init
   

3. Or manually repair (advanced):

4. Edit .beads/issues.jsonl
5. Ensure each line is valid JSON
6. Remove trailing commas
7. Fix improperly escaped strings

Symptoms: Cub refuses to proceed because you have modified files.

Cause: Cub requires a clean git state by default for safety.

Solution:

git add .
git commit -m "Save work before cub run"

git stash
# Later: git stash pop

{
  "clean_state": {
    "require_commit": false
  }
}

Symptoms: Git operations fail because directory isn't a git repo.

Solution: Initialize git:

git init
git add .
git commit -m "Initial commit"

Symptoms: Cub can't create a work branch because it exists.

Solution:

1. Check existing branches:

   git branch -a
   

2. Delete old branches if needed:

   git branch -D old-branch-name
   

3. Or use a different session name:

   cub run --name my-unique-session
   

Symptoms: Clean state verification detects test failures.

Cause: Your test suite is failing.

Solution:

1. Run tests manually to see errors:

   npm test        # or pytest, make test, etc.
   

2. Fix the failures in your source code.

3. Or disable test requirement in .cub.json:

   {
     "clean_state": {
       "require_tests": false
     }
   }
   

Symptoms: Cub warns about invalid configuration files.

Cause: Your .cub.json or global config has invalid JSON.

Solution:

1. Validate JSON syntax:

   # Project config
   jq . .cub.json
   
   # Global config
   jq . ~/.config/cub/config.json
   

2. Fix common errors:

Symptoms: Error about unrecognized backend option.

Cause: Invalid backend specified in config or environment.

Solution: Use a valid backend:

• beads - Beads CLI (.beads/issues.jsonl)
• json - JSON file (prd.json)

# CLI override
cub run --backend json

# Or in .cub.json
{
  "backend": "json"
}

Symptoms: You want to migrate from prd.json to beads but get an error.

Solution: Create a minimal prd.json first:

cat > prd.json << 'EOF'
{
  "tasks": [
    {
      "id": "task-1",
      "title": "Example task",
      "description": "A task to migrate",
      "status": "open"
    }
  ]
}
EOF

Then migrate:

cub --migrate-to-beads-dry-run  # Preview changes
cub --migrate-to-beads          # Execute migration