Troubleshooting

Installation Issues

`pip install attestix` fails with dependency conflicts

ERROR: Cannot install attestix because these package versions have conflicting dependencies.

Solution: Use a virtual environment to isolate dependencies:

python -m venv attestix-env
source attestix-env/bin/activate  # Linux/macOS
attestix-env\Scripts\activate     # Windows
pip install attestix

Python version error

ERROR: Package 'attestix' requires Python >=3.10

Solution: Attestix requires Python 3.10 or later. Check your version with python --version and upgrade if needed.

MCP Server Issues

Claude Code cannot find the MCP server

Error: MCP server "attestix" failed to start

Possible causes:

Wrong Python path - Use the full path to your Python executable:

{
  "mcpServers": {
    "attestix": {
      "type": "stdio",
      "command": "/usr/bin/python3",
      "args": ["/full/path/to/attestix/main.py"]
    }
  }
}

Virtual environment not activated - If Attestix is installed in a venv, point to that Python:
```
{
  "command": "/path/to/venv/bin/python"
}
```
Missing dependencies - Run pip install -r requirements.txt in the Attestix directory.

Tools not showing up in Claude Code

Solution: Restart Claude Code after updating the MCP config. Run /mcp to verify the server is connected and showing 47 tools.

Identity Issues

"Identity not found" when verifying

{
  "valid": false,
  "checks": { "exists": false }
}

Cause: The agent ID does not exist in identities.json. This can happen if:

The identity was created in a different working directory (Attestix uses local JSON files)
The identity was revoked or erased (GDPR Article 17)
You're using a different Attestix instance

Solution: Check identities.json in your working directory. Create a new identity if needed.

Signature verification fails

{
  "valid": false,
  "checks": { "signature_valid": false }
}

Cause: The signing key has changed since the identity was created. This happens when:

.signing_key.json was deleted or replaced
You moved the Attestix data files to a different machine
The identity was created by a different Attestix instance

Solution: Identities are bound to the signing key that created them. If you need to verify identities across machines, you must use the same .signing_key.json file.

Credential Issues

"Credential has been revoked"

{
  "valid": false,
  "checks": { "not_revoked": false }
}

Cause: The credential was explicitly revoked via revoke_credential. Revocation is permanent.

Solution: Issue a new credential with issue_credential.

Ed25519Signature2020 verification fails externally

Cause: External verifiers may expect different canonicalization. Attestix uses JCS (RFC 8785) for JSON canonicalization before signing.

Solution: Ensure your external verifier supports:

Ed25519Signature2020 proof type
JCS (JSON Canonicalization Scheme) per RFC 8785
Multibase-encoded public keys (base58btc, z prefix)

Compliance Issues

Self-assessment blocked for high-risk system

{
  "error": "High-risk systems in Annex III categories require third-party assessment"
}

This is intentional. EU AI Act Article 43 prohibits self-assessment for most high-risk AI systems. You must use a third-party notified body:

compliance_svc.record_conformity_assessment(
    agent_id=agent_id,
    assessment_type="third_party",  # not "self"
    assessor_name="TUV Rheinland AG",
    result="pass",
)

Compliance status shows missing items

{
  "compliant": false,
  "completion_pct": 60.0,
  "missing": ["conformity_assessment", "declaration_of_conformity"]
}

Solution: Follow the steps in the EU AI Act Compliance Guide. The typical workflow is:

Create identity
Record training data (Article 10)
Record model lineage (Article 11)
Create compliance profile
Record conformity assessment
Generate declaration of conformity

Blockchain Issues

"No RPC URL configured"

Error: ATTESTIX_BASE_RPC_URL environment variable not set

Solution: Set the Base L2 RPC URL in your environment:

export ATTESTIX_BASE_RPC_URL="https://mainnet.base.org"

Or use a provider like Alchemy:

export ATTESTIX_BASE_RPC_URL="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"

See the Configuration page for all environment variables.

Transaction fails with "insufficient funds"

Cause: Blockchain anchoring requires a small amount of ETH on Base L2 for gas fees (typically less than $0.01).

Solution: Fund the wallet associated with ATTESTIX_WALLET_PRIVATE_KEY with a small amount of ETH on Base L2.

All core Attestix features work without blockchain. If you don't need on-chain proof, skip the blockchain configuration entirely. Identity, credentials, compliance, and provenance all work fully offline.

Delegation Issues

"Capability not in parent scope"

{
  "error": "Cannot delegate capabilities not held by issuer"
}

Cause: When chaining delegations, the child delegation cannot grant capabilities that the parent delegation does not have.

Solution: Only delegate capabilities that are a subset of what the issuing agent has been granted:

# Parent has: ["data_access", "reporting"]
# Child can delegate at most: ["data_access", "reporting"]
# Child CANNOT delegate: ["admin", "delete"]

Delegation expired

{
  "valid": false,
  "checks": { "not_expired": false }
}

Cause: UCAN delegations are time-bounded. The expiry_hours parameter sets the lifetime.

Solution: Create a new delegation with create_delegation. Consider using longer expiry times if appropriate for your use case.

Data and Storage

Where does Attestix store data?

By default, Attestix creates JSON files in the current working directory:

identities.json - Agent identity tokens
credentials.json - Verifiable credentials
delegations.json - UCAN delegation tokens
provenance.json - Audit trail entries
reputation.json - Interaction records
.signing_key.json - Ed25519 keypair (keep this safe)

Check the FAQ for general questions
Search GitHub Issues
Open a new issue with your error message and environment details