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.

---

Analysis Times Out or Hangs

Symptoms:

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

Causes:

• Large codebase
• Insufficient system resources

Solutions:

1. Check cache hit rate: Look for cache hit messages in logs. If you’re not getting cache hits, analysis runs from scratch every time.

2. Increase cache TTL:

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

3. Reduce analysis scope: Use .arxoignore or config to exclude large dependencies (e.g. node_modules/, vendor/, .venv/, target/).

4. Monitor system resources:

   ps aux | grep arxo-mcp
   top -p $(pgrep arxo-mcp)

---

Stale Cache Results

Symptoms:

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

Solutions:

1. Wait for TTL to expire (default 5 minutes).

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"]
   }

---

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). Analysis can run without a config file; the server uses defaults.

Solutions:

1. Create a config — Use arxo_config_suggest to generate a suggested arxo.yaml, or create one manually.

2. Provide an explicit config path:

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

---

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 for analysis tools)
   • section: string (optional, for arxo_config_help)

2. Check for trailing commas:

   { "project_path": "." }

---

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"]
}

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

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

---

Performance

• Exclude large directories in config or .arxoignore (e.g. node_modules/, vendor/, .venv/, target/).
• Increase cache TTL if you run analysis repeatedly on the same project.

---

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 a small project — Try analyzing a small codebase to isolate the issue
4. Report a bug — Open an issue at github.com/arxohq/arxo with MCP config, log output, and steps to reproduce

---

Related Pages

• Configuration — Server arguments and client setup
• Workflows — Example usage
• Tools — Tool reference