Troubleshooting

Troubleshooting

This page covers common issues when running the Arxo MCP server, how to debug them, and where to find logs.

---

Common Errors

Binary Not Found or Permission Denied

Error:

Cannot find executable: /path/to/arxo-mcp

Solution:

1. Verify the binary exists at the path specified in your MCP config:

   ls -la /path/to/arxo-mcp

2. Check if the binary is executable:

   chmod +x /path/to/arxo-mcp

3. Test that the binary runs standalone:

   /path/to/arxo-mcp --help

4. If using a relative path like ${workspaceFolder}/target/release/arxo-mcp, verify it resolves correctly by checking your workspace root.

---

Tool Returns “Requires Full Arxo” Error

Error:

{
  "error": "This tool requires the full arxo binary with git worktree support."
}

Affected tools:

• analyze_with_baseline
• suggest_refactors

Explanation: These tools depend on features (git worktree creation, advanced refactoring algorithms) that are only available in the full arxo CLI binary, not in the lightweight MCP server.

Solution: Use the CLI for these operations:

# Baseline comparison
arxo analyze --baseline main

# Refactoring suggestions
arxo analyze --preset risk --format json | jq '.recommendations'

See CLI Comparison for a full mapping between MCP tools and CLI commands.

---

Resource Returns Placeholder Message

Error:

{
  "message": "Dependency graph requires full arxo (import_graph not in loader output)"
}

Affected resources:

• graph://dependency/<project_path>

Explanation: The dependency graph resource requires the full import graph from the analysis engine, which is not included in the lightweight MCP server output.

Solution: Use the analyze_architecture tool with a preset that includes graph metrics:

analyze_architecture({
  "project_path": ".",
  "preset": "coupling"
})

The response will include metrics like centrality, modularity, and propagation_cost that are derived from the dependency graph.

---

Analysis Times Out or Hangs

Symptoms:

• Tool calls take several minutes or never return
• MCP server logs show no activity

Causes:

• Large codebase (>100k LOC)
• Full preset on a complex project
• Insufficient system resources

Solutions:

1. Use a faster preset:

   analyze_architecture({ "project_path": ".", "preset": "quick" })

2. Check cache hit rate: Look for [INFO] Cache hit for project: ... in logs. If you’re not getting cache hits, analysis runs from scratch every time.

3. Increase cache TTL:

   {
     "command": "/path/to/arxo-mcp",
     "args": ["--cache-ttl", "600"]
   }

4. Reduce analysis scope: Use .arxoignore to exclude large dependencies:

   node_modules/
   vendor/
   .venv/
   target/

5. Monitor system resources:

   # Check if the MCP server process is running
   ps aux | grep arxo-mcp
   
   # Check memory usage
   top -p $(pgrep arxo-mcp)

---

Stale Cache Results

Symptoms:

• Changes to code not reflected in analysis results
• Old violations still showing after fixes

Causes:

• Cache TTL hasn’t expired
• Config file changed but cache key didn’t update

Solutions:

1. Wait for TTL to expire: Default is 5 minutes. Check your --cache-ttl setting.

2. Restart the MCP server: In Cursor: reload the window or restart Cursor.

3. Reduce cache TTL for development:

   {
     "command": "/path/to/arxo-mcp",
     "args": ["--cache-ttl", "60"]
   }

4. Force a fresh analysis by changing the config: Temporarily add/remove a policy invariant in arxo.yaml to invalidate the cache key.

---

Config File Not Found

Error:

Config file not found: arxo.yaml

Explanation: The MCP server looks for arxo.yaml in the project root (the project_path parameter).

Solutions:

1. Initialize a config file:

   cd /path/to/project
   arxo init

2. Provide an explicit config path:

   analyze_architecture({
     "project_path": "/path/to/project",
     "config_path": "/path/to/custom-config.yaml"
   })

3. Run without a config file: Most tools work without arxo.yaml. Policy evaluation requires it, but you can pass inline policy YAML:

   evaluate_policy({
     "project_path": ".",
     "policy_yaml": "policy:\n  invariants:\n    - metric: scc.max_cycle_size\n      op: '<='\n      value: 0"
   })

---

JSON-RPC Parse Errors

Error:

Failed to parse JSON-RPC request

Causes:

• Malformed JSON in tool parameters
• Incorrect parameter types (e.g., string instead of array)

Solutions:

1. Validate parameter types:

   • project_path: string (required)
   • file_paths: array of strings (for analyze_file_impact)
   • preset: string (optional)

2. Check for trailing commas:

   // Bad
   { "project_path": ".", "preset": "ci", }
   
   // Good
   { "project_path": ".", "preset": "ci" }

3. Escape special characters in paths:

   { "project_path": "/path/with spaces/project" }  // OK, JSON handles spaces

---

Debugging

Enabling Debug Logs

Set the RUST_LOG environment variable in your MCP config:

{
  "command": "/path/to/arxo-mcp",
  "env": {
    "RUST_LOG": "arxo_mcp=debug"
  }
}

Or use the --log-level argument:

{
  "command": "/path/to/arxo-mcp",
  "args": ["--log-level", "debug"]
}

Log Levels

Level	What you see
error	Only errors (minimal logging)
warn	Errors + warnings
info	Errors + warnings + tool calls, cache hits/misses
debug	Everything above + parameter details, analysis steps
trace	Maximum verbosity (very noisy, use sparingly)

Viewing Logs in Cursor

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Search for “MCP: Show Server Logs”
3. Select Arxo from the server list
4. Logs appear in a new panel

Logs are written to stderr so they don’t interfere with the JSON-RPC stream on stdout.

Log Output Examples

Cache hit:

[INFO] Cache hit for project: /path/to/project, preset: ci

Cache miss:

[INFO] Cache miss, running analysis for project: /path/to/project

Tool execution:

[INFO] Calling tool: analyze_architecture
[DEBUG] Parameters: { "project_path": ".", "preset": "quick" }
[INFO] Analysis completed in 3.2s

Error:

[ERROR] Failed to load config: No such file or directory (os error 2)

---

Inspecting MCP Communication

Manual Testing with CLI

You can test the MCP server manually via stdin/stdout. This is useful for debugging without an MCP client:

# Start the server
./target/release/arxo-mcp

# Send a JSON-RPC request (paste this as a single line):
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

# Expected response: list of available tools

Using jq to Format Responses

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  ./target/release/arxo-mcp | \
  jq '.result.tools[] | {name, description}'

---

Performance Issues

Large Codebase (>100k LOC)

Symptoms:

• Analysis takes >30 seconds
• MCP client times out

Solutions:

1. Use the quick preset for interactive workflows: Reserve full, risk, and coupling for CI or periodic reviews.

2. Exclude large dependencies: Add to .arxoignore:

   **/node_modules/**
   **/vendor/**
   **/.venv/**
   **/target/**
   **/build/**
   **/dist/**

3. Increase memory limit (if using Docker or containers): The MCP server is a Rust binary with low overhead, but analysis of very large projects can use 500MB–2GB RAM.

4. Run analysis in CI instead: For projects >500k LOC, consider running full analysis in CI and using MCP only for check_cycles and get_hotspots.

Cache Thrashing

Symptoms:

• Frequent cache misses even when code hasn’t changed
• Analysis runs every time

Causes:

• Config file changing (e.g., auto-formatting tools)
• Git history changing (if repo is frequently rebased)

Solutions:

1. Check cache hit rate in logs:

   [INFO] Cache hit for project: ...

2. Increase cache TTL:

   {
     "args": ["--cache-ttl", "900"]  // 15 minutes
   }

3. Increase cache entries:

   {
     "args": ["--max-cache-entries", "1000000"]  // 1M entries
   }

---

Environment Variables

Variable	Purpose	Example
RUST_LOG	Log level control	arxo_mcp=debug
ARCH0_CONFIG	Override config file path	/path/to/arxo.yaml
NO_COLOR	Disable colored output	1

---

Getting Help

If you’ve tried the steps above and still have issues:

1. Check logs — Enable debug level and inspect stderr output
2. Verify binary — Run arxo-mcp --help to confirm it works standalone
3. Test with simple project — Try analyzing a small test project to isolate the issue
4. Report a bug — Open an issue at github.com/arxohq/arxo with:
   • MCP config (.cursor/mcp.json or equivalent)
   • Log output with RUST_LOG=arxo_mcp=debug
   • Project characteristics (language, size, structure)
   • Error message and steps to reproduce

---

Related Pages

• Configuration — Server arguments and client setup
• Workflows — Example usage patterns
• Advanced — Caching strategy and custom tool composition
• CLI Comparison — Mapping MCP tools to CLI commands