Troubleshooting

Common issues and solutions for Arena CLI.

Installation issues

npm install fails with permission errors

Configure npm to use a directory you own:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Install without sudo
npm install -g @whitegodkingsley/arena-cli

arena: command not found

The npm global bin directory is not in your PATH:

# Find where npm installs global packages
npm config get prefix

# Add to PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Or use npx instead
npx @whitegodkingsley/arena-cli process video.mp4

Python issues

Python not found

# macOS
brew install python3

# Ubuntu/Debian
sudo apt install python3 python3-pip

# Verify
python3 --version

Python version too old

Arena requires Python 3.10–3.12. Using pyenv is recommended:

curl https://pyenv.run | bash
pyenv install 3.11.0
pyenv global 3.11.0

Python dependencies missing

Repair Arena's isolated runtime rather than installing packages into global Python:

arena setup --check
arena setup --force

FFmpeg issues

FFmpeg not found

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Verify
ffmpeg -version

Unsupported codec errors

Reinstall FFmpeg with all codecs:

# macOS
brew reinstall ffmpeg

# Ubuntu (enable multiverse)
sudo add-apt-repository multiverse
sudo apt update && sudo apt install ffmpeg

API issues

OpenAI API key not found

# Set environment variable
export OPENAI_API_KEY="sk-..."

# Or use Arena's interactive owner-only credential store
arena config set openai_api_key

# Verify
arena config get openai_api_key

Rate limit exceeded (429)

Arena handles rate limits automatically with exponential backoff. If you're consistently hitting limits:

• Use gpt-4o-mini (higher rate limits)
• Process fewer clips at once (-n 3)
• Add delays between batch jobs
• Upgrade your OpenAI API tier

Insufficient quota

Add credits at platform.openai.com/account/billing.

Processing issues

No clips generated

Possible causes:

• Video too short — Use videos longer than 2 minutes
• Duration constraints too strict — Try --min 20 --max 90
• All clips failed quality gate — Export layers to debug

# Check why clips were rejected
arena process video.mp4 --export-layers
cat output/editorial_layers/layer3_validated.json | \
  jq '.[] | select(.verdict=="REJECT") | {rejection_reason}'

No clips passed validation

Layer 3 is a strict quality gate. Relax your duration constraints:

# More permissive constraints
arena process video.mp4 --min 15 --max 120

Processing is very slow

• Use gpt-4o-mini instead of gpt-4o
• Reduce clip count (-n 3)
• Check your internet connection

Memory errors

# Use fast mode (less memory)
arena process video.mp4 --fast

# Or reduce video resolution first
ffmpeg -i video.mp4 -vf scale=-1:720 -c:a copy video_720p.mp4
arena process video_720p.mp4

Quality issues

Clips have poor cut points

The 4-layer editorial system should handle this. If clips still start or end awkwardly, try adding more padding:

arena process video.mp4 --padding 1.0

Clips are too similar

• Reduce clip count (-n 3) for more diversity
• Increase duration range for more variety

Low video quality output

If using --fast mode, clips are stream-copied without re-encoding. Remove the flag for full re-encoding:

arena process video.mp4  # Without --fast

Diagnostics

# Run full system check
arena diagnose

# Check versions
arena --version
node --version
python3 --version
ffmpeg -version

# Debug mode (verbose output)
arena process video.mp4 --debug

# Save debug log
arena process video.mp4 --debug 2>&1 | tee debug.log

Getting more help

• GitHub Issues — Report bugs and request features
• GitHub Issues — Ask questions and share tips

When reporting an issue, include:

• Full error message
• Command you ran
• Output from arena diagnose
• Your OS and version