Troubleshooting

Troubleshooting

This guide covers common issues you might encounter when using Arxo.

Installation Issues

Installing the Arxo CLI

Arxo is distributed as a closed-source pre-built binary. You do not need Rust to run it. Download the latest release for your platform from GitHub Releases and add the arxo binary to your PATH. See Installation for details.

---

Analysis Issues

No Files Found / Empty Graph

Symptoms:

• “0 files analyzed”
• Empty import graph
• No metrics computed

Causes & Solutions:

1. Wrong directory:

   # Check current directory
   pwd
   
   # Specify correct path
   arxo analyze --path /path/to/project

2. Excluded by patterns:

   # Check .arxo.yaml exclude patterns
   import_graph:
     exclude:
       - "**/*"  # ❌ Excludes everything!

   Remove or fix overly broad exclusions.

3. Unsupported file types: Arxo only parses:

   • .ts, .tsx, .js, .jsx, .mjs
   • .py
   • .rs
   • .java
   • .kt, .kts
   • .go

   Check you have source files in these languages.

4. Files in node_modules:

   # Ensure node_modules is excluded
   import_graph:
     exclude:
       - "**/node_modules/**"

---

Analysis Too Slow

Symptoms: Analysis takes >5 minutes on small projects

Solutions:

1. Use quick mode:

   arxo analyze --quick

2. Exclude test/build directories:

   import_graph:
     exclude:
       - "**/test/**"
       - "**/tests/**"
       - "**/dist/**"
       - "**/build/**"
       - "**/*.test.ts"
       - "**/*.spec.ts"

3. Limit languages:

   import_graph:
     languages:
       - typescript  # Only analyze TypeScript

4. Use caching:

   # Ensure caching is enabled (default)
   arxo analyze  # First run: slow
   arxo analyze  # Subsequent: fast

5. Clear corrupted cache:

   arxo cache clear

---

High Memory Usage

Symptoms: Process killed, OOM errors

Solutions:

1. Limit graph size:

   import_graph:
     max_nodes: 5000
     max_edges: 20000

2. Exclude large dependencies:

   import_graph:
     exclude:
       - "**/node_modules/**"
       - "**/vendor/**"

3. Use file-level grouping (less memory than folder grouping):

   import_graph:
     group_by: file

4. Analyze in parts:

   # Analyze frontend separately
   arxo analyze --path ./frontend
   
   # Analyze backend separately
   arxo analyze --path ./backend

---

Parsing Errors

Error: “Failed to parse file: src/example.ts”

Causes & Solutions:

1. Invalid syntax: Fix syntax errors in your source files:

   # Check with native tools
   tsc --noEmit  # TypeScript
   python -m py_compile file.py  # Python
   cargo check  # Rust

2. Unsupported syntax: Some bleeding-edge language features might not be supported yet.

   Workaround: Exclude problematic files:

   import_graph:
     exclude:
       - "**/problematic-file.ts"

3. Encoding issues: Ensure files are UTF-8 encoded:

   file -I src/example.ts
   # Should show: charset=utf-8

---

Policy Violations

False Positives

Symptoms: Policy violations that seem incorrect

Solutions:

1. Check grouping: File-level grouping might show false cycles. Try folder grouping:

   import_graph:
     group_by: folder
     group_depth: 2

2. Inspect actual violations:

   # Get detailed JSON report
   arxo analyze --format json --output report.json
   
   # Extract violations
   jq '.violations' report.json

3. Adjust thresholds:

   policy:
     invariants:
       - metric: propagation_cost.system.ratio
         op: "<="
         value: 0.20  # Was 0.15, too strict

4. Exclude specific patterns:

   import_graph:
     exclude:
       - "**/legacy/**"  # Exclude legacy code temporarily

---

Cannot Reproduce Locally

Symptoms: CI fails, but local run passes

Solutions:

1. Cache differences:

   # Clear cache
   arxo cache clear
   
   # Run analysis
   arxo analyze

2. Git history depth: CI might have shallow clone:

   # GitHub Actions
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0  # Full history for git-based metrics

3. Config file location:

   # Explicitly specify config in CI
   arxo analyze --config .arxo.yaml

4. Environment differences:

   # Check arxo version
   arxo --version
   
   # Ensure same version in CI and locally

---

Configuration Issues

Invalid Configuration

Error: “Invalid config: unknown field ‘foo’”

Solution: Validate config:

arxo config validate --config .arxo.yaml

Common mistakes:

1. Typos:

   # ❌ Wrong
   metriks:  # Typo
     - id: scc
   
   # ✅ Correct
   metrics:
     - id: scc

2. Indentation:

   # ❌ Wrong (2 spaces required)
   policy:
       invariants:  # 4 spaces
   
   # ✅ Correct
   policy:
     invariants:  # 2 spaces

3. Invalid operators:

   # ❌ Wrong
   policy:
     invariants:
       - metric: scc.max_cycle_size
         op: "less_than"  # Invalid
   
   # ✅ Correct
   policy:
     invariants:
       - metric: scc.max_cycle_size
         op: "<="  # Use: ==, !=, <, <=, >, >=

---

Config Not Found

Error: “Config file not found: .arxo.yaml”

Solutions:

1. Create config:

   arxo init  # Creates .arxo.yaml

2. Specify path:

   arxo analyze --config path/to/config.yaml

3. Check working directory:

   pwd  # Should be project root
   ls -la  # Should show .arxo.yaml

---

Metric Issues

Metric Not Found

Error: “Unknown metric: foo”

Solution: List available metrics:

arxo metrics list

Check metric ID spelling:

# ❌ Wrong
metrics:
  - id: strong_connected_components

# ✅ Correct
metrics:
  - id: scc

---

Metric Returns Zero

Symptoms: Metric always returns 0 or empty

Causes:

1. Missing required data: Some metrics need specific graphs:

   • scc needs import_graph
   • Call graph metrics need call_graph

   Enable required data:

   data:
     import_graph:
       enabled: true
     call_graph:
       enabled: true

2. No violations found: Zero might be correct! Check if your code is actually healthy:

   # Get full report
   arxo analyze --format json | jq '.results[] | select(.id=="scc")'

---

Output Issues

Cannot Parse JSON Output

Error: “Unexpected token in JSON”

Solution: Ensure quiet mode:

# ❌ Wrong (includes progress output)
arxo analyze --format json

# ✅ Correct (JSON only)
arxo analyze --format json --quiet

Or redirect to file:

arxo analyze --format json --output report.json

---

HTML Report Not Opening

Issue: HTML report is empty or doesn’t render

Solutions:

1. Open in browser:

   arxo analyze --format html --output report.html
   open report.html  # macOS
   xdg-open report.html  # Linux
   start report.html  # Windows

2. Check file size:

   ls -lh report.html
   # Should be > 1KB

3. Validate HTML:

   head -n 20 report.html
   # Should start with <!DOCTYPE html>

---

Caching Issues

Stale Cache Results

Symptoms: Changes not reflected in analysis

Solution: Clear cache:

# Clear all cache
arxo cache clear

# Or disable cache
arxo analyze --no-analysis-cache

---

Cache Too Large

Issue: ~/.cache/arxo using too much disk space

Solutions:

1. Clear old entries:

   arxo cache clear

2. Set custom cache location:

   run_options:
     cache_path: /tmp/arxo-cache

3. Disable cache:

   run_options:
     disable_cache: true

---

Language-Specific Issues

TypeScript: Cannot Resolve Paths

Issue: Path mappings not recognized

Solution: Ensure tsconfig.json is present:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Arxo reads tsconfig.json for path resolution.

---

Python: Imports Not Resolved

Issue: Python imports not found

Solutions:

1. Add __init__.py to packages:

   touch src/__init__.py
   touch src/utils/__init__.py

2. Check PYTHONPATH:

   .arxo.yaml

   languages:
     python:
       paths:
         - src
         - lib

---

Rust: Workspace Not Detected

Issue: Rust workspace members not analyzed

Solution: Ensure Cargo.toml has workspace config:

[workspace]
members = [
  "crates/*",
]

---

Performance Debugging

Enable timing reports:

arxo analyze --report-timings

Output shows time spent on each stage:

Parsing: 2.3s
Import graph: 1.1s
Call graph: 0.8s
SCC: 0.2s
Propagation cost: 1.5s
...

---

Getting Help

Generate Debug Report

# Environment info
arxo doctor

# Full analysis with JSON output (use RUST_LOG=debug for verbose logs)
arxo analyze --format json --output debug-report.json

Check Logs

CLI Logs:

# Enable verbose logging
RUST_LOG=debug arxo analyze

MCP Server Logs:

If using the MCP server in Cursor or another IDE:

1. Open the MCP server logs panel in your IDE
2. Select “Arxo” server
3. Set log level to debug: --log-level debug in MCP config
4. Review tool execution, cache hits, and errors

See MCP Configuration for log settings.

Report Issues

When reporting issues, include:

1. Arxo version: arxo --version
2. OS and Rust version: rustc --version
3. Project type (TypeScript/Python/etc.)
4. Error message or unexpected behavior
5. Config file (if applicable)
6. Debug report: arxo doctor

---

Common Error Messages

Error	Meaning	Solution
Failed to parse	Syntax error	Fix source file syntax
Config validation failed	Invalid YAML	Run arxo config validate
Metric not found	Wrong metric ID	Run arxo metrics list
No files analyzed	Wrong path/excludes	Check path and exclusions
Policy violation	Threshold exceeded	Adjust policy or fix code
Out of memory	Graph too large	Limit nodes or exclude files

---

Next Steps

• Configuration Guide - Full config reference
• CLI Reference - Command options
• MCP Workflows - AI-assisted debugging
• Policy Examples - Real-world policies
• CI Integration - Set up CI