Troubleshooting

Solutions to common issues you may encounter when using the Codified Orchestrator.

Common Issues

Installation Issues

Problem: pip install -e . fails with dependency errors

The installation may fail due to outdated Python or pip versions.

Solution: Ensure Python 3.10+ and pip upgrade

# Verify Python version
python --version  # should be 3.10+

# Upgrade pip
pip install --upgrade pip

# Install with dev dependencies
pip install -e ".[dev]"

Configuration Issues

Problem: cco config init fails

Configuration initialization may fail due to permissions or missing directories.

Solution: Check config file permissions and manually create

# Ensure config directory exists
mkdir -p ~/.codified-orchestrator

# Preview config before writing
cco config init --print

# Or initialize with explicit profile
cco config init --profile direct-minimax

API Key Issues

Problem: "Invalid API key" errors

API key is missing, expired, or incorrectly configured.

Solution: Update your API key via command or environment

# Rotate API key for a provider
cco secret rotate --provider minimax --key sk-xxx

# Or set via environment variable for the session
MINIMAX_API_KEY=sk-xxx cco ask "test"

# Verify key is loaded correctly
cco config show --key MINIMAX_API_KEY

Memory Issues

Problem: AOMA memory not loading

Memory system may have corrupted indices or incorrect project namespace.

Solution: Check and rebuild memory system

# Check memory system status
cco mem status

# Rebuild memory indices
cco mem consolidate

# Reset to default project
cco mem project-switch --project default

# List all projects
cco mem project-list

Debug Mode

Enable Debug Logging

Run any command with debug logging to see detailed execution traces:

# Enable debug logging
cco --log-level DEBUG plan --repo /path/to/repo --task "test"

# Save debug output to file
cco --log-level DEBUG plan --repo /path/to/repo --task "test" 2>&1 | tee debug.log

# Debug with timestamps
cco --log-level DEBUG --log-timestamp true ask "analyze this"

Trace Run Execution

Trace a specific run to understand what happened during execution:

# Find run_id from previous output
cco runs list --limit 5

# Trace specific run with JSON output
cco trace <run_id> --json

# Trace with full artifact dump
cco trace <run_id> --artifacts --json

# Compare two runs
cco trace <run_id_1> --compare <run_id_2>

Verbose Doctor

Run comprehensive diagnostics with verbose output:

# Basic doctor check
cco doctor --repo /path/to/repo

# Verbose diagnostic output
cco doctor --repo /path/to/repo --verbose

# JSON output for scripting
cco doctor --repo /path/to/repo --verbose --json

# Include system info
cco doctor --repo /path/to/repo --verbose --json --include-system

Validation Issues

Cross-Reference Failures

Validate cross-references in your repository to ensure consistency:

# Validate cross-references
python scripts/validate_crossrefs.py --repo /path/to/repo

# JSON output for CI integration
python scripts/validate_crossrefs.py --repo /path/to/repo --json

# Verbose output showing all checks
python scripts/validate_crossrefs.py --repo /path/to/repo --verbose

# Fix detected issues automatically
python scripts/validate_crossrefs.py --repo /path/to/repo --fix

Pre-flight Check Failures

When pre-flight checks fail, verify each component manually:

Check	Command	Expected Result
Git status	`git status`	Clean working directory or expected changes
Dependencies	`pip list`	All required packages installed
Disk space	`df -h`	Sufficient space available (>1GB)
Memory	`free -m`	Available memory >512MB
Network	`ping -c 1 api.minimax.io`	Network connectivity working

Getting Help

Show All Commands

# List all available commands
cco help

# Show command groups
cco help --verbose

# Show all subcommands for a specific command
cco task --help

Command-Specific Help

# Get help for a specific command
cco task --help

# Get examples for a command
cco ask --help --examples

# Show all options for a command
cco plan --help --all

Check Version

# Basic version check
cco version

# Verbose version with dependencies
cco version --verbose

# Show build info
cco version --build

Environment Variables

The following environment variables control CCO behavior:

Variable	Purpose	Example
`CODIFIED_PROJECT_KEY`	AOMA project namespace	`my-project`
`MINIMAX_API_KEY`	API key for primary provider	`sk-xxx...`
`CODIFIED_ACTIVE_PROFILE`	Config profile to use	`direct-minimax`
`CODIFIED_LOG_LEVEL`	Logging verbosity	`DEBUG`
`CODIFIED_CONFIG_PATH`	Override config file location	`~/.config/cco/config.yaml`
`CODIFIED_RUNS_DIR`	Override run artifacts directory	`/var/runs`

Support

Running Diagnostics

The best way to get help is to run diagnostics and include the output in your support request:

# Run comprehensive diagnostics
cco doctor --repo /path/to/repo --verbose --json > diagnostics.json

# Query recent audit log
cco audit query --limit 10 --json

# Export full system state
cco doctor --repo /path/to/repo --include-system --json > full-report.json

Reviewing Past Issues

Check the observatory dashboard for patterns in past runs:

# Open observatory dashboard
open docs/observatory/index.html

# Or via CLI
cco observatory open

# Query past issues from audit log
cco audit query --filter "level=error" --limit 20 --json

Still Stuck?

Run cco doctor --repo /path/to/repo --json and review the audit log with cco audit query --limit 10 --json to gather diagnostic information before requesting support.