Supported library reference. Rust, Node.js, Python and Go remain supported in a separate workspace. This chapter can contain historical version or installation text; use the current package guide. Extended CLI examples use jacs-compat in 0.15. See the current MCP guide for actual runtime profiles and the release inventory for published versions.

Error Codes

This reference documents error codes and messages you may encounter when using JACS.

CLI Exit Codes

Configuration Errors

Missing Configuration

Error: Configuration file not found: jacs.config.json

Cause: JACS cannot find the configuration file.

Solution:

# Initialize JACS to create configuration
jacs init

# Or specify a custom config path
JACS_CONFIG_PATH=./custom.config.json jacs agent verify

Invalid Configuration

Error: Invalid configuration: missing required field 'jacs_key_directory'

Cause: Configuration file is missing required fields.

Solution: Ensure your jacs.config.json contains all required fields:

{
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  "jacs_agent_key_algorithm": "ring-Ed25519",
  "jacs_default_storage": "fs"
}

Key Directory Not Found

Error: Key directory not found: ./jacs_keys

Cause: The specified key directory does not exist.

Solution:

# Create the directory
mkdir -p ./jacs_keys

# Or run init to create everything
jacs init

Cryptographic Errors

Private Key Not Found

Error: Private key file not found: private.pem

Cause: The private key file is missing from the key directory.

Solution:

# Generate new keys
jacs agent create --create-keys true

Invalid Key Format

Error: Failed to parse private key: invalid PEM format

Cause: The key file is corrupted or in wrong format.

Solution:

• Regenerate keys with jacs agent create --create-keys true
• Ensure the key file is not corrupted

Key Password Required

Error: Private key is encrypted but no password provided

Cause: Encrypted private key requires password.

Solution:

export JACS_PRIVATE_KEY_PASSWORD="your-password"
jacs document create -f doc.json

Algorithm Mismatch

Error: Key algorithm 'ring-Ed25519' does not match configured algorithm 'pq2025'

Cause: The key file was created with a different algorithm than configured.

Solution:

• Update config to match key algorithm, or
• Regenerate keys with the correct algorithm

Signature Errors

Verification Failed

Error: Document verification failed: signature does not match content

Cause: Document content has been modified after signing.

Solution:

• The document may have been tampered with
• Re-sign the document if you have the original content

Missing jacsSignature Field

Error: Document missing jacsSignature field

Cause: Document was not signed or signature was removed.

Solution:

# Create a signed document
jacs document create -f unsigned-doc.json

Missing Signature (v0.10.0)

Error / Status: MissingSignature — surfaced by verify-text / verify-image (and the corresponding binding methods) when the input file does not carry an embedded JACS signature.

Default behaviour is permissive — missing signature is a typed status, not a thrown error. Strict mode opts in to treating it as an error.

When to pick strict. Pick strict when a missing signature is genuinely a failure (release-gate, post-merge audit, CI on a branch that should always be signed). Pick permissive when verification runs against files that may legitimately be unsigned (the first PR introducing a signature).

Solution: sign the file, or — if missing signatures are expected — switch the call site to permissive mode and inspect result.status.

Invalid Signature Format

Error: Invalid signature format: expected base64 encoded string

Cause: The signature field is malformed.

Solution:

• Re-sign the document
• Verify the document hasn't been corrupted

Unknown Signing Algorithm

Error: Unknown signing algorithm: unknown-algo

Cause: Document was signed with an unsupported algorithm.

Solution:

• Use a supported user-facing algorithm for new keys: ed25519, pq2025 (ring-Ed25519 remains a legacy input and canonical wire label)

DNS Verification Errors

DNSSEC Validation Failed

Error: strict DNSSEC validation failed for <owner> (TXT not authenticated). Enable DNSSEC and publish DS at registrar

Cause: DNSSEC mode was requested but the TXT response wasn't authenticated.

Solution:

1. Enable DNSSEC for your domain zone
2. Publish the DS record at your registrar
3. Wait for propagation (up to 48 hours)

DNS Record Not Found

Error: DNS TXT lookup failed for <owner> (record missing or not yet propagated)

Cause: The JACS TXT record doesn't exist or hasn't propagated.

Solution:

1. Verify the TXT record was created:

   dig _v1.agent.jacs.yourdomain.com TXT
   

2. Wait for DNS propagation (can take up to 48 hours)
3. Confirm record name and value are correct

DNS Required

Error: DNS TXT lookup required (domain configured) or provide embedded fingerprint

Cause: Strict DNS mode is active because a domain is configured.

Solution:

• Publish the TXT record, or
• Run with --no-dns during initial setup:

  jacs agent verify --no-dns
  

DNS Lookup Timeout

Error: DNS lookup timed out for <domain>

Cause: DNS server did not respond in time.

Solution:

• Check network connectivity
• Try again later
• Verify DNS server is accessible

Document Errors

Invalid JSON

Error: Failed to parse document: invalid JSON at line 5

Cause: Document file contains invalid JSON.

Solution:

• Validate JSON with a linter
• Check for syntax errors (missing commas, quotes)

Schema Validation Failed

Error: Schema validation failed: missing required field 'amount'

Cause: Document doesn't conform to the specified schema.

Solution:

# Check which fields are required by the schema
cat schema.json | jq '.required'

# Add missing fields to your document

Document Not Found

Error: Document not found: 550e8400-e29b-41d4-a716-446655440000

Cause: The specified document ID doesn't exist in storage.

Solution:

• Verify the document ID is correct
• Check the storage directory

Version Mismatch

Error: Document version mismatch: expected v2, got v1

Cause: Attempting to update with incorrect base version.

Solution:

• Get the latest version of the document
• Apply updates to the correct version

Agreement Errors

Agreement Not Found

Error: Document has no jacsAgreement field

Cause: Attempting agreement operations on a document without an agreement.

Solution:

# Create an agreement first
jacs document create-agreement -f doc.json -i agent1-id,agent2-id

Already Signed

Error: Agent has already signed this agreement

Cause: Attempting to sign an agreement that was already signed by this agent.

Solution:

• No action needed, the signature is already present

Not Authorized

Error: Agent is not in the agreement's agentIDs list

Cause: Attempting to sign with an agent not listed in the agreement.

Solution:

• Only agents listed in jacsAgreement.agentIDs can sign

Agreement Locked

Error: Cannot modify document: agreement is complete

Cause: Attempting to modify a document with a completed agreement.

Solution:

• Create a new version/agreement if changes are needed

Storage Errors

Storage Backend Error

Error: Storage error: failed to write to filesystem

Cause: Unable to write to the configured storage backend.

Solution:

• Check filesystem permissions
• Verify storage directory exists
• Check disk space

AWS S3 Error

Error: S3 error: AccessDenied

Cause: AWS credentials don't have required permissions.

Solution:

• Verify IAM permissions include s3:GetObject, s3:PutObject
• Check bucket policy
• Verify credentials are correct

Connection Error

Error: Failed to connect to storage: connection refused

Cause: Cannot connect to remote storage backend.

Solution:

• Check network connectivity
• Verify endpoint URL is correct
• Check firewall rules

HTTP/MCP Errors

Request Verification Failed

Error: JACS request verification failed

Cause: Incoming HTTP request has invalid JACS signature.

Solution:

• Ensure client is signing requests correctly
• Verify client and server are using compatible keys

Response Verification Failed

Error: JACS response verification failed

Cause: Server response has invalid signature.

Solution:

• Check server JACS configuration
• Verify server is signing responses

Middleware Configuration Error

Error: JACSExpressMiddleware: config file not found

Cause: Middleware cannot find JACS configuration.

Solution:

app.use('/api', JACSExpressMiddleware({
  configPath: './jacs.config.json'  // Verify path is correct
}));

Debugging Tips

Enable Verbose Output

# CLI verbose mode
jacs document verify -f doc.json -v

# Environment variable
export JACS_DEBUG=true

Check Configuration

# Display current configuration
jacs config read

Verify Agent

# Verify agent is properly configured
jacs agent verify -v

Test Signing

# Create a test document
echo '{"test": true}' > test.json
jacs document create -f test.json -v

See Also

• Configuration Reference - Configuration options
• CLI Command Reference - CLI usage
• Security Model - Security details