Skip to content
Arxo Arxo

Troubleshooting

Troubleshooting

Section titled “Troubleshooting”

This page covers common issues when integrating the arxo-engine library and how to resolve them.

Engine Not Found

Section titled “Engine Not Found”

Symptom

Error: Failed to load arxo-engine: library not found

Causes and solutions

  • Rust (arxo-loader)
    The loader looks for the engine in: ARCH0_ENGINE_PATH, same directory as the binary, then ~/.cache/arxo/engine/v{version}/, then may attempt a CDN download. Ensure the engine binary was downloaded at build time or place the library in one of these locations and set ARCH0_ENGINE_PATH if needed.

    Check that the loader actually has the engine:

    Terminal window
    ls ~/.cache/arxo/engine/
    # or
    echo $ARCH0_ENGINE_PATH

  • Node.js / Python
    Ensure the package is installed and the native addon path is correct:

    Terminal window
    ls node_modules/@arxo/engine/lib/
    python -c "import arxo; print(arxo.__file__)"

  • FFI (C/Go/Zig)
    The dynamic library must be loadable. See FFI: Library not found below.

License Validation Failed

Section titled “License Validation Failed”

Symptom

Error: Invalid or expired license

Solutions

  1. Verify key
    Ensure the key is set and passed correctly:

    Terminal window
    echo $ARCH0_LICENSE_KEY

    When using the FFI or loader, pass the same key (e.g. in config or env) that your license expects.

  2. Check expiration
    If you have the CLI: arxo license info (or equivalent from your distribution).

  3. Open source / free tier
    Free tier often requires a public repo (e.g. GitHub/GitLab) with an OSI-approved license. Ensure the project and visibility match the product’s requirements.

  4. Commercial
    Contact the vendor (e.g. support@arxo.dev) for renewal or a new key.

Platform Not Supported

Section titled “Platform Not Supported”

Symptom

Error: No pre-built binary for your platform

Solutions

  • Supported platforms are typically:

    • Linux: x86_64, ARM64
    • macOS: x86_64, ARM64 (Apple Silicon)
    • Windows: x86_64

  • If your OS/arch is not listed, you may need to:

    • Use a supported platform (e.g. CI on Linux x86_64), or
    • Request a custom build from the vendor.

FFI: Library Not Found

Section titled “FFI: Library Not Found”

Symptom (Linux)

error while loading shared libraries: libarxo_engine.so: cannot open shared object file

Solutions

  • Linux

    Terminal window
    export LD_LIBRARY_PATH=/path/to/dir/containing/lib:$LD_LIBRARY_PATH

    Or install system-wide:

    Terminal window
    sudo cp libarxo_engine.so /usr/local/lib/
    sudo ldconfig

  • macOS

    Terminal window
    export DYLD_LIBRARY_PATH=/path/to/dir/containing/lib:$DYLD_LIBRARY_PATH

  • Windows
    Put the DLL in the same directory as your executable, or in a directory on PATH.

FFI: Undefined Symbols

Section titled “FFI: Undefined Symbols”

Symptom

undefined reference to `arxo_engine_new'

Solution

Link against the engine and point the linker to its location:

Terminal window
gcc -o myapp main.c -L/path/to/lib -larxo_engine

Use the correct library name for your platform (libarxo_engine.so, libarxo_engine.dylib, or arxo_engine.dll).

FFI: ABI Compatibility

Section titled “FFI: ABI Compatibility”
  • The FFI uses the C ABI; same major version of header and library should be used together.
  • Major version upgrades may change or remove symbols; recompile and relink with the new header and library.
  • Do not mix headers from one version with libraries from another.

Configuration Errors

Section titled “Configuration Errors”

Symptom

Analysis fails immediately with an error about invalid config (e.g. missing field, wrong type).

Solutions

  • YAML/JSON
    Validate syntax and that required fields are present. See Configuration for the full schema.

  • Paths
    project_path (or equivalent) must point to an existing directory. Use absolute paths or paths relative to the process current working directory, depending on how your integration invokes the engine.

  • FFI
    Config is passed as a JSON string. Ensure the string is valid JSON and matches the Config schema (e.g. data.language, metric_preset, report.format).

Parsing or Analysis Failures

Section titled “Parsing or Analysis Failures”

Symptom

Engine runs but reports parsing errors, or analysis fails mid-run for specific files.

Solutions

  • Excludes
    Noisy or generated code can be excluded via data.import_graph.exclude or data.language_presets. Add patterns for node_modules, dist, target, .next, etc., as needed.

  • Language
    Set data.language to the primary language (e.g. typescript, rust, python) instead of auto if detection is wrong.

  • Large repos
    Use metric_preset: "quick" or a smaller set of metrics, enable caching, and consider run_options.incremental if supported to speed up repeated runs.

Cache Issues

Section titled “Cache Issues”

Symptom

Stale results after changing code or config, or errors mentioning cache.

Solutions

  • Disable cache
    Set run_options.disable_cache: true (or equivalent) to force a full rebuild.

  • Clear cache
    Delete the cache directory (e.g. .arxo-cache or the path in config) and re-run.

  • Config/source changes
    Some builds invalidate cache when config or source paths change; if not, clear the cache manually after big changes.

Thread Safety

Section titled “Thread Safety”

The engine is not thread-safe. For concurrent workloads:

  • Use one engine instance per thread, or
  • Serialize access with a mutex/lock.

Do not share a single engine handle across threads without synchronization.

Getting More Help

Section titled “Getting More Help”