Skip to content

Troubleshooting

Having trouble with Cub? This section covers diagnostic tools, common issues, and detailed error references.

  • FAQ

    Answers to commonly asked questions about Cub installation, usage, and configuration.

    Read the FAQ

  • Common Issues

    Solutions to frequent problems with installation, harnesses, tasks, and git.

    Common Issues

  • Error Reference

    Complete list of error messages with causes and solutions.

    Error Reference

Diagnostic Tools

Cub includes several built-in tools to help diagnose issues.

The Doctor Command

The cub doctor command runs comprehensive diagnostics on your system:

cub doctor

It checks:

Category What It Checks
System Bash version, required tools (jq, git)
Harnesses Availability of claude, codex, gemini, opencode
Configuration JSON validity, deprecated options
Project Structure prd.json or .beads/, agent.md, prompt.md
Symlinks Correct targets in legacy layout
Git State Uncommitted changes, branches, merges
Tasks State validation, stuck tasks, recommendations

Example output:

[OK] System checks passed
[OK] Configuration valid
[OK] Harness: claude available
[XX] Harness: codex not found
[OK] Task backend: beads
[OK] Git state: clean

Debug Logging

Enable verbose output to see exactly what Cub is doing:

cub run --debug

Debug output includes:

  • Configuration loading steps
  • Harness invocation details
  • Task selection logic
  • API calls and responses
  • File operations

Log Files

Structured logs are saved in .cub/logs/:

# List log files
ls -la .cub/logs/

# Watch live logs
tail -f .cub/logs/session-*.jsonl

# Parse with jq
jq . .cub/logs/session-*.jsonl | head -100

Each log entry contains:

{
  "timestamp": "2026-01-17T14:30:22Z",
  "event_type": "task_end",
  "task_id": "cub-042",
  "task_title": "Add user authentication",
  "duration_sec": 145,
  "exit_code": 0
}

Task Artifacts

Examine output from completed tasks:

# List all artifacts
cub artifacts

# View specific task artifacts
cub artifacts cub-042

# Browse artifact directory
ls -la .cub/artifacts/

Getting Help

If the troubleshooting guides don't solve your issue:

1. Run Diagnostics

Collect diagnostic information:

# Run doctor and save output
cub doctor > doctor-output.txt

# Capture recent logs
cp .cub/logs/session-*.jsonl logs-for-support/

2. Enable Debug Mode

Reproduce the issue with debug output:

cub run --debug --once 2>&1 | tee debug-output.txt

3. Check Known Issues

Search existing issues on GitHub:

4. Report a Bug

If you've found a new issue, open a bug report with:

  • Output from cub doctor
  • Debug logs from reproduction
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Your environment (OS, Python version, harness version)

Quick Fixes

Before diving into detailed troubleshooting, try these quick fixes:

Harness not found 
# Check which harnesses are installed
which claude codex gemini opencode

# Install Claude Code (recommended)
npm install -g @anthropic-ai/claude-code
Task file errors 
# Validate JSON syntax
jq . prd.json

# Or if using beads
bd list
Permission denied 
# Make scripts executable
chmod +x cub cub-init
Git state issues 
# Check current state
git status

# Commit or stash changes
git add . && git commit -m "WIP"
# Or: git stash
Configuration problems 
# Validate project config
jq . .cub.json

# Validate global config
jq . ~/.config/cub/config.json

Next Steps