Error Catalog

Version: 2.0.0-alpha.6 Last Updated: 2025-10-13

Complete reference of errors, exceptions, and failure modes in CLI Audit tool, with causes, resolutions, and troubleshooting guidance.

Error Categories
Configuration Errors
Installation Errors
Environment Detection Errors
Package Manager Errors
Validation Errors
Network Errors
System Errors
Exit Codes
Troubleshooting

Error Categories

Category	Severity	Retryable	Examples
Configuration	High	No	Invalid config values, unsupported versions
Installation	Medium	Sometimes	Network failures, lock contention, command failures
Environment	Low	No	Invalid override values
Package Manager	High	No	PM not available, no suitable PM found
Validation	Medium	No	Binary not found, version mismatch
Network	Medium	Yes	Timeouts, connection refused, DNS failures
System	High	Sometimes	Permission denied, disk full, command not found

Configuration Errors

CONFIG-001: Unsupported Config Version

Error Message:

ValueError: Unsupported config version: X. Expected version 1

Cause:

Configuration file specifies unsupported schema version
Current supported version: 1

Resolution:

Update config file to use version: 1
Review Configuration Files for current schema

Example:

# ❌ Wrong
version: 2

# ✅ Correct
version: 1

CONFIG-002: Invalid Environment Mode

Error Message:

ValueError: Invalid environment_mode: X. Must be one of: auto, ci, server, workstation

Cause:

Configuration specifies invalid environment mode
Valid modes: auto, ci, server, workstation

Resolution:

# ❌ Wrong
environment:
  mode: production

# ✅ Correct
environment:
  mode: server

CONFIG-003: Invalid Reconciliation Strategy

Error Message:

ValueError: Invalid reconciliation strategy: X. Must be 'parallel' or 'aggressive'

Cause:

Invalid reconciliation preference value
Valid values: parallel (keep all), aggressive (remove non-preferred)

Resolution:

preferences:
  reconciliation: parallel  # or 'aggressive'

CONFIG-004: Invalid Breaking Changes Policy

Error Message:

ValueError: Invalid breaking_changes setting: X. Must be 'accept', 'warn', or 'reject'

Cause:

Invalid breaking_changes preference value
Valid values: accept, warn, reject

Resolution:

preferences:
  breaking_changes: warn  # accept, warn, or reject

CONFIG-005: Invalid Timeout Value

Error Message:

ValueError: Invalid timeout_seconds: X. Must be between 1 and 60

Cause:

Timeout value outside valid range (1-60 seconds)

Resolution:

preferences:
  timeout_seconds: 10  # 1-60 seconds

CONFIG-006: Invalid Max Workers

Error Message:

ValueError: Invalid max_workers: X. Must be between 1 and 32

Cause:

Worker count outside valid range (1-32)

Resolution:

preferences:
  max_workers: 16  # 1-32 workers

CONFIG-007: Invalid Cache TTL

Error Message:

ValueError: Invalid cache_ttl_seconds: X. Must be between 60 and 86400 (1 minute to 1 day)

Cause:

Cache TTL outside valid range (60-86400 seconds)

Resolution:

preferences:
  cache_ttl_seconds: 3600  # 1 hour (60-86400 seconds)

CONFIG-008: Config File Not Found

Error Message:

ValueError: Could not load config from specified path: /path/to/config.yml

Cause:

Custom config path specified but file doesn't exist or can't be read
YAML parser not available (PyYAML not installed)

Resolution:

Verify file exists: ls -l /path/to/config.yml
Check file permissions: chmod 644 config.yml
Install PyYAML: pip install pyyaml
Validate YAML syntax: yamllint config.yml

Installation Errors

INSTALL-001: Installation Failed at Step

Error Message:

Installation failed at step: <description>
<error_details>

Cause:

Command execution failed during installation
Network issues, permission problems, or package manager errors

Resolution:

Check error details for specific cause
For network errors: retry or check connectivity
For permission errors: ensure sudo access or use user-level PM
For lock errors: wait and retry

Retry Logic:

Network errors: Auto-retry with exponential backoff
Lock contention: Auto-retry with exponential backoff
Other errors: No auto-retry (manual intervention required)

INSTALL-002: Post-Install Validation Failed

Error Message:

Post-install validation failed for <tool_name>

Cause:

Tool installed but binary not found in PATH
Binary exists but version check failed
Tool name differs from package name

Resolution:

Check PATH: echo $PATH
Find binary manually: find ~/.local ~/.cargo /usr/local -name '<tool>'
Verify installation: <tool> --version
Update PATH if needed:
```
export PATH="$HOME/.local/bin:$PATH"
```

INSTALL-003: Command Timeout

Error Message:

Command timed out after Xs

Cause:

Installation command exceeded configured timeout
Slow network, large download, or unresponsive package manager

Resolution:

Increase timeout:

preferences:
  timeout_seconds: 30  # Increase from default 5s

Check network connectivity
Try different package manager

INSTALL-004: Command Not Found

Error Message:

Command not found: <command>

Cause:

Package manager binary not in PATH
Package manager not installed

Resolution:

Install package manager:

# For cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# For pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Verify installation: which <command>
Update PATH if needed

INSTALL-005: Installation Error (Generic)

Error Message:

Installation error: <details>

Cause:

Unexpected exception during installation
Python errors, file system issues, or system problems

Resolution:

Check error details for specific cause
Enable debug mode: CLI_AUDIT_DEBUG=1
Check system logs: journalctl -xe
Report issue if persistent

Installation Error (InstallError)

Custom Exception: InstallError

Properties:

message: Human-readable error message
retryable: Whether error can be retried
remediation: Suggested fix

Usage:

try:
    result = install_tool(...)
except InstallError as e:
    print(f"Error: {e.message}")
    if e.retryable:
        print("This error can be retried")
    if e.remediation:
        print(f"Suggested fix: {e.remediation}")

Retryable Errors:

Network-related:

connection refused
connection timed out
connection reset
temporary failure
network unreachable
could not resolve host

Lock contention:

could not get lock
lock file exists
waiting for cache lock
dpkg frontend lock

Exit codes:

75 (EAGAIN - temporary failure)
111 (connection refused)
128 (git error)

Environment Detection Errors

ENV-001: Invalid Environment Override

Error Message:

ValueError: Invalid environment override: X. Must be one of: auto, ci, server, workstation

Cause:

Invalid override value passed to detect_environment()
Valid values: auto, ci, server, workstation

Resolution:

# ❌ Wrong
env = detect_environment(override="production")

# ✅ Correct
env = detect_environment(override="server")

ENV-002: Low Confidence Detection

Warning Message:

Environment detected with low confidence: <confidence>%

Cause:

Ambiguous environment indicators
Missing expected environment variables or system signals

Resolution:

Use explicit override:
```
env = detect_environment(override="ci")
```

Or in config:

environment:
  mode: ci  # Explicit mode

Set environment-specific variables (CI, DISPLAY, etc.)

Package Manager Errors

PM-001: No Suitable Package Manager Found

Error Message:

ValueError: No suitable package manager found for <tool>. Please install a package manager for <language>.

Cause:

No package manager available for tool's language/ecosystem
Package managers not in PATH

Resolution:

Install recommended package manager:

Python:

pip install --user pipx
python -m pipx ensurepath

Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Node:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Configure package manager hierarchy:

preferences:
  package_managers:
    python: [uv, pipx, pip]
    rust: [cargo]
    node: [npm, pnpm, yarn]

PM-002: Package Manager Not Found

Error Message:

ValueError: Package manager not found: <pm_name>

Cause:

Specified package manager not registered in system
Typo in package manager name

Resolution:

Check available PMs: See PHASE2_API_REFERENCE.md
Verify spelling: cargo, pipx, npm, etc.
Install missing PM (see PM-001)

Validation Errors

VALID-001: Binary Not Found in PATH

Error Message:

Binary not found in PATH: <tool_name>

Cause:

Installation succeeded but binary not in PATH
Tool installed to unexpected location
PATH not updated after installation

Resolution:

Find binary:
```
find ~ -name '<tool>' 2>/dev/null
```

Update PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"

Reload shell: source ~/.bashrc

VALID-002: Version Detection Failed

Warning Message:

Could not determine version for <tool_name>

Cause:

Tool doesn't support standard version flags
Version output format not recognized

Resolution:

Check manually:

<tool> --version
<tool> -V
<tool> version

Tool still functional despite version detection failure
Report issue if version should be detectable

VALID-003: Version Mismatch

Warning Message:

Installed version <actual> differs from target <expected>

Cause:

Package manager installed different version than requested
Latest version changed between plan generation and execution

Resolution:

Check if acceptable: minor version differences usually OK

For exact version, specify in config:

tools:
  tool_name:
    version: "1.2.3"  # Exact version

Network Errors

NET-001: Connection Timeout

Error Message:

connection timed out

Cause:

Network latency or package repository unresponsive
Firewall blocking connections

Resolution:

Check network: ping pypi.org
Increase timeout:
```
preferences:
  timeout_seconds: 30
```

Configure proxy if needed:

export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

NET-002: Connection Refused

Error Message:

connection refused

Cause:

Package repository temporarily unavailable
Port blocked by firewall
Wrong repository URL

Resolution:

Wait and retry (auto-retry enabled)
Check repository status
Try alternative package manager

NET-003: DNS Resolution Failed

Error Message:

could not resolve host

Cause:

DNS server unreachable
Domain name doesn't exist
Network connectivity issue

Resolution:

Check DNS: nslookup pypi.org
Test connectivity: ping 8.8.8.8

Configure DNS:

# Add to /etc/resolv.conf
nameserver 8.8.8.8
nameserver 1.1.1.1

System Errors

SYS-001: Permission Denied

Error Message:

Permission denied

Cause:

Insufficient permissions for operation
System-level package manager requires sudo
Directory not writable

Resolution:

Use user-level package manager:

preferences:
  package_managers:
    python: [uv, pipx, pip]  # uv/pipx don't need sudo

Or use sudo:
```
sudo python3 cli_audit.py
```
Fix directory permissions:
```
chmod 755 ~/.local/bin
```

SYS-002: Disk Space Exhausted

Error Message:

No space left on device

Cause:

Insufficient disk space for installation
Download cache full

Resolution:

Check space: df -h

Clean cache:

# pip
pip cache purge

# cargo
cargo clean

# apt
sudo apt clean

Free up space or expand disk

SYS-003: File Not Found

Error Message:

FileNotFoundError: [Errno 2] No such file or directory

Cause:

Required file or directory missing
Incorrect path specified

Resolution:

Verify path exists
Create missing directories:
```
mkdir -p ~/.config/cli-audit
```
Check file permissions

Exit Codes

Code	Meaning	Retryable	Action
`0`	Success	N/A	Continue
`1`	General error	No	Check error message
`2`	Misuse of command	No	Fix command syntax
`75`	Temporary failure	Yes	Auto-retry
`111`	Connection refused	Yes	Auto-retry
`126`	Command not executable	No	Check permissions
`127`	Command not found	No	Install package manager
`128`	Invalid exit argument	Yes	Auto-retry (git errors)
`130`	Terminated by Ctrl+C	No	User interrupted
`-1`	Timeout or system error	Sometimes	Check timeout settings

Troubleshooting

General Debugging Steps

Enable Debug Mode:
```
CLI_AUDIT_DEBUG=1 python3 cli_audit.py
```

Enable Verbose Logging:

result = install_tool(..., verbose=True)

Check System Requirements:

python3 --version  # 3.9+
which pip pipx cargo npm
echo $PATH

Validate Configuration:

from cli_audit import load_config, validate_config

config = load_config()
warnings = validate_config(config)
for warning in warnings:
    print(f"⚠️  {warning}")

Common Resolution Patterns

Network Issues:

Increase timeout
Check connectivity
Configure proxy
Try offline mode: CLI_AUDIT_OFFLINE=1

Permission Issues:

Use user-level package managers (uv, pipx, cargo)
Fix directory permissions: chmod 755
Or use sudo (system PMs only)

Package Manager Issues:

Verify PM installed: which <pm>
Update PATH
Configure PM hierarchy in config
Try alternative PM

Validation Issues:

Check PATH
Verify binary exists: which <tool>
Test manually: <tool> --version
Update PATH and reload shell

Getting Help

Check Documentation:
- CLI_REFERENCE.md - Command reference
- PHASE2_API_REFERENCE.md - API documentation
- TESTING.md - Testing and debugging

Enable Tracing:

CLI_AUDIT_TRACE=1 CLI_AUDIT_TRACE_NET=1 python3 cli_audit.py 2> trace.log

Report Issue: Include:
- Error message and stack trace
- Operating system and version
- Python version
- Tool and package manager versions
- Debug output

FilesExpand file tree

ERROR_CATALOG.md

Latest commit

History

ERROR_CATALOG.md

File metadata and controls

Error Catalog

Table of Contents

Error Categories

Configuration Errors

CONFIG-001: Unsupported Config Version

CONFIG-002: Invalid Environment Mode

CONFIG-003: Invalid Reconciliation Strategy

CONFIG-004: Invalid Breaking Changes Policy

CONFIG-005: Invalid Timeout Value

CONFIG-006: Invalid Max Workers

CONFIG-007: Invalid Cache TTL

CONFIG-008: Config File Not Found

Installation Errors

INSTALL-001: Installation Failed at Step

INSTALL-002: Post-Install Validation Failed

INSTALL-003: Command Timeout

INSTALL-004: Command Not Found

INSTALL-005: Installation Error (Generic)

Installation Error (InstallError)

Custom Exception: InstallError

Environment Detection Errors

ENV-001: Invalid Environment Override

ENV-002: Low Confidence Detection

Package Manager Errors

PM-001: No Suitable Package Manager Found

PM-002: Package Manager Not Found

Validation Errors

VALID-001: Binary Not Found in PATH

VALID-002: Version Detection Failed

VALID-003: Version Mismatch

Network Errors

NET-001: Connection Timeout

NET-002: Connection Refused

NET-003: DNS Resolution Failed

System Errors

SYS-001: Permission Denied

SYS-002: Disk Space Exhausted

SYS-003: File Not Found

Exit Codes

Troubleshooting

General Debugging Steps

Common Resolution Patterns

Getting Help

Related Documentation