​

Troubleshooting Guide

This guide covers common issues you might encounter when using Arc Memory and provides solutions to resolve them.

​

Installation Issues

​

Python Version Errors

Issue: Error message about unsupported Python version.

Solution:

1. Check your Python version: python --version
2. Install a supported version (3.9 or higher):

   # Using pyenv
   pyenv install 3.10.0
   pyenv global 3.10.0
   
   # Or download from python.org
   

3. Create a new virtual environment with the correct Python version:

   python3.10 -m venv venv
   source venv/bin/activate
   

​

Dependency Conflicts

Issue: Errors about conflicting dependencies or version requirements.

Solution:

1. Use a clean virtual environment:

   python -m venv venv
   source venv/bin/activate
   

2. Install Arc Memory in the virtual environment:

   pip install arc-memory
   

3. If conflicts persist, try installing with the --ignore-installed flag:

   pip install --ignore-installed arc-memory
   

​

Installation Fails on Windows

Issue: Installation fails with compilation errors on Windows.

Solution:

1. Install Visual C++ Build Tools:
   • Download from Microsoft’s website
   • Select “C++ build tools” during installation
2. Install using a wheel file if available:

   pip install arc_memory-0.3.0-cp310-cp310-win_amd64.whl
   

3. If all else fails, consider using WSL (Windows Subsystem for Linux)

​

Authentication Issues

​

GitHub Authentication Fails

Issue: GitHub authentication fails with error messages.

Solution:

1. Check your token has the required scopes:
   • repo (for private repositories)
   • read:user
   • read:org (if accessing organization repositories)
2. Verify the token is valid by testing it with the GitHub API:

   curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
   

3. Try authenticating with a new token:

   arc auth gh --token YOUR_NEW_TOKEN
   

4. Check for network issues or proxy settings that might block GitHub API access

​

Token Not Found

Issue: Error message about missing GitHub token.

Solution:

1. Explicitly provide the token:

   arc auth gh --token YOUR_TOKEN
   

2. Check if the token file exists:

   cat ~/.arc/github_token
   

3. Set the token as an environment variable:

   export GITHUB_TOKEN=your_token
   arc build
   

​

Build Issues

​

Build Process Fails

Issue: The arc build command fails with errors.

Solution:

1. Run with debug logging:

   arc build --debug
   

2. Check if Git is installed and accessible:

   git --version
   

3. Verify you’re in a Git repository:

   git rev-parse --is-inside-work-tree
   

4. Try building with limited scope:

   arc build --max-commits 100 --days 30
   

5. Check for disk space issues:

   df -h
   

​

GitHub API Rate Limit Exceeded

Issue: Build fails with GitHub API rate limit errors.

Solution:

1. Authenticate with a GitHub token:

   arc auth gh --token YOUR_TOKEN
   

2. Reduce the scope of your build:

   arc build --max-commits 500 --days 30
   

3. Use incremental builds when possible:

   arc build --incremental
   

4. Wait for rate limits to reset (usually 1 hour)

​

Database Errors

Issue: Errors related to the SQLite database.

Solution:

1. Check database integrity:

   arc doctor
   

2. Try rebuilding from scratch:

   arc build --clean
   

3. Check SQLite version:

   sqlite3 --version
   

4. Verify write permissions to the output directory:

   touch .arc/test.txt && rm .arc/test.txt
   

​

Query Issues

​

No Results Found

Issue: Commands like trace, why, or relate return no results.

Solution:

1. Verify the file path is correct:

   ls -la path/to/file.py
   

2. Check if the file is tracked in Git:

   git ls-files | grep path/to/file.py
   

3. Increase the search depth:

   arc why file path/to/file.py 42 --max-depth 5
   

4. Ensure the knowledge graph is built:

   arc build
   

​

Performance Issues

Issue: Queries are very slow or time out.

Solution:

1. Limit the query depth:

   arc relate node commit:abc123 --max-depth 2
   

2. Filter by specific edge or node types:

   arc relate node commit:abc123 --edge-types MODIFIES,PART_OF
   

3. Use incremental builds to keep the graph size manageable:

   arc build --incremental
   

4. Check system resources:

   top  # or htop
   

​

Simulation Issues

​

Simulation Fails to Start

Issue: The arc sim run command fails to start.

Solution:

1. Run with debug logging:

   arc sim run --debug
   

2. Check if the required dependencies are installed:

   pip install arc-memory[simulation]
   

3. Try a different sandbox environment:

   arc sim run --sandbox local
   

4. Verify your changes are valid:

   git diff
   

​

Sandbox Environment Issues

Issue: Errors related to the sandbox environment.

Solution:

1. For Docker sandbox issues:
   • Check if Docker is running: docker ps
   • Verify Docker permissions: docker run hello-world
   • Restart Docker: systemctl restart docker or restart Docker Desktop
2. For E2B sandbox issues:
   • Check internet connectivity
   • Verify your E2B API key: echo $E2B_API_KEY
   • Try the local sandbox instead: arc sim run --sandbox local

​

Inaccurate Simulation Results

Issue: Simulation results seem inaccurate or incomplete.

Solution:

1. Try with memory enabled:

   arc sim run --memory
   

2. Use a more isolated sandbox:

   arc sim run --sandbox e2b
   

3. Run multiple scenarios:

   arc sim run --scenario network_latency,memory_usage,cpu_usage
   

4. Ensure your repository has sufficient test coverage

​

Plugin Issues

​

Plugin Not Found

Issue: Error about a plugin not being found.

Solution:

1. Check if the plugin is installed:

   pip list | grep plugin-name
   

2. Verify the plugin is properly registered:

   arc doctor --plugins
   

3. Install the plugin:

   pip install arc-memory-plugin-name
   

4. If developing a plugin, install in development mode:

   pip install -e .
   

​

Plugin Errors During Build

Issue: Errors from plugins during the build process.

Solution:

1. Run with debug logging:

   arc build --debug
   

2. Try building without the problematic plugin:

   arc build --exclude-plugins plugin-name
   

3. Check plugin compatibility with your Arc Memory version:

   pip show arc-memory
   pip show arc-memory-plugin-name
   

4. Update the plugin:

   pip install --upgrade arc-memory-plugin-name
   

​

General Troubleshooting Steps

If you encounter issues not covered above:

1. Check logs: Run commands with --debug flag
2. Verify dependencies: Run arc doctor to check system requirements
3. Update Arc Memory: Run pip install --upgrade arc-memory
4. Check GitHub issues: Visit GitHub Issues to see if others have reported the same problem
5. Clean installation: Try uninstalling and reinstalling Arc Memory
6. System resources: Ensure you have sufficient disk space, memory, and CPU resources

​

Getting Help

If you’re still experiencing issues:

1. Open an issue on GitHub
2. Include detailed information:
   • Arc Memory version: arc --version
   • Python version: python --version
   • Operating system and version
   • Complete error message and stack trace
   • Steps to reproduce the issue
3. Check the FAQ for common questions

​

See Also

• Dependencies Guide - For a complete list of dependencies
• Test Environment Setup - For setting up a test environment
• GitHub Integration Guide - For GitHub-specific troubleshooting