Troubleshooting Guide

Common issues and their solutions.

Setup Issues

"Not a git repository"

Problem: Arial requires a git repository.

Solution:

git init
arial init

"Arial is already initialized"

Problem: The .arial/ directory already exists.

Solution:

arial init --force

"ANTHROPIC_API_KEY not set"

Problem: Arial needs an API key to run agents.

Solution:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Add to your shell profile for persistence:

echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

Planning Issues

"No active run"

Problem: No workstreams have been created.

Solution:

arial plan --specs ./specs

"Error: --specs is required"

Problem: Missing required option.

Solution:

arial plan --specs ./path/to/specs

"Specs directory not found"

Problem: The specified path doesn't exist.

Solution:

# Check the path exists
ls ./specs

# Create if needed
mkdir specs
echo "# My Feature" > specs/feature.md

"No markdown files found"

Problem: The specs directory has no .md files.

Solution:

# Check for markdown files
ls ./specs/*.md

# Create one
echo "# My Feature\n\nDescription here." > specs/feature.md

Execution Issues

"No active run"

Problem: Trying to run before planning.

Solution:

arial plan --specs ./specs
arial run

Workstream Stuck in "running"

Problem: Arial was interrupted leaving a workstream in running state.

Solution:

When you run arial run again, Arial detects this and handles it:

• Workstreams marked as paused will resume
• If truly stuck, clear state and re-plan:

rm -rf .arial/state.json
arial plan --specs ./specs -y
arial run

Workstream Failed

Problem: A workstream couldn't complete.

Solution:

All Workstreams Already Completed

Problem: Nothing to run.

Solution:

If you want to run again:

rm -rf .arial/state.json
arial plan --specs ./specs -y
arial run

Git Issues

"Could not determine current branch"

Problem: Git repository is in a detached HEAD state.

Solution:

git checkout main  # or your branch
arial plan --specs ./specs

Worktree Errors

Problem: Git worktree issues from previous runs.

Solution:

# List worktrees
git worktree list

# Remove orphaned worktrees
git worktree prune

# If needed, manually remove
rm -rf .arial/workspaces/*
git worktree prune

Merge Conflicts After Completion

Problem: Branches can't merge cleanly.

Solution:

Manual resolution:

git checkout main
git merge arial/<workstream-id>
# Resolve conflicts
git add .
git commit

Or abandon and retry:

git merge --abort
# Update spec to avoid the conflict
arial plan --specs ./specs -y
arial run

Display Issues

TUI Not Working

Problem: Terminal doesn't support the TUI.

Solution:

arial run --no-tui

Or use verbose mode:

arial run --verbose

Output Garbled

Problem: Terminal encoding or capability issues.

Solution:

arial run --no-tui

State Issues

Corrupt State

Problem: state.json is corrupted or invalid.

Solution:

# Remove state and re-plan
rm -rf .arial/state.json
arial plan --specs ./specs

Want to Start Fresh

Problem: Need to clear everything and start over.

Solution:

# Remove all Arial state
rm -rf .arial

# Clean up worktrees
git worktree prune

# Clean up branches
git branch | grep "arial/" | xargs git branch -D

# Re-initialize
arial init
arial plan --specs ./specs

Recovery Procedures

Full Reset

If everything is broken:

# 1. Remove Arial data
rm -rf .arial

# 2. Clean up git worktrees
git worktree list
git worktree prune

# 3. Remove Arial branches
git branch | grep "arial/" | xargs -r git branch -D

# 4. Start fresh
arial init
arial plan --specs ./specs
arial run

Recover Work from Failed Run

If a workstream failed but made useful changes:

# 1. Check the branch exists
git branch -a | grep arial

# 2. View changes
git diff main..arial/<workstream-id>

# 3. Cherry-pick or merge useful commits
git checkout main
git cherry-pick <commit-hash>
# or
git merge arial/<workstream-id>

Getting Help

Check Status

arial status
arial status --json

Verbose Output

arial run --verbose

Check Version

arial --version
node --version
git --version

Environment Check

# Check API key is set
echo $ANTHROPIC_API_KEY | head -c 10

# Check in git repo
git status

Quick Fixes Reference