Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Troubleshooting

Common issues and solutions when installing or using JACS.

Installation Issues

pip install fails

Published 0.16.1 wheels and this source checkout require Python 3.11–3.14. If no pre-built wheel exists for your platform, install the Rust toolchain and build from source:

pip install maturin
make build-jacspy  # from the repository root

npm install fails

Native npm binaries cover macOS x64/arm64, Linux x64/arm64 for glibc and Linux x64 for musl. There is no Windows addon; a Windows CLI archive is a separate artifact. For custom source builds, use make build-jacsnpm from the repository root with the documented Node and Rust toolchains.

Alpine Linux / musl libc

Published 0.16.1 includes a Python musllinux x86_64 wheel and an npm musl x86_64 addon; neither has a musl arm64 build. CLI archives are glibc-only; the Python/npm CLI shims reject musl even when library APIs work. Match the artifact to architecture and libc; see deployment compatibility.

Configuration Issues

Config not found

Run jacs-compat quickstart --name my-agent --domain my-agent.example.com to auto-create a config, or copy the example:

cp jacs.config.example.json jacs.config.json

Private key decryption failed

Wrong or missing password. Check JACS_PRIVATE_KEY_PASSWORD. For jacs-compat, you may also set JACS_PASSWORD_FILE to a file that contains only the password, or use jacs-compat keychain set to store the password in the OS keychain. Set exactly one explicit source; if both env var and password file are set, CLI fails by design. The OS keychain is only consulted when neither env var nor password file is present.

Algorithm detection failed

Set jacs_agent_key_algorithm in the config, or pass the algorithm explicitly to quickstart(...) / create(...). User-facing values are pq2025 and ed25519; the legacy input alias and canonical Ed25519 wire label are ring-Ed25519.

Runtime Issues

Agent creation fails

Ensure the data and key directories exist and are writable. By default these are ./jacs_data and ./jacs_keys.

Signature verification fails

Ensure the signer's public key is accessible. If verifying a document from another agent, you may need to import their public key or use the trust store.

Documents not found

Check the jacs_data_directory path in your config. Documents are stored as JSON files in that directory.

Building from Source

git clone https://github.com/HumanAssisted/JACS.git
cd JACS

# Rust core + CLI
cargo build --release
cargo install --path jacs-cli --locked

# Python binding
make build-jacspy  # from the repository root

# Node.js binding
make build-jacsnpm

Requires Rust 1.97+ (install via rustup).

Getting Help