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 MCP 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)
Its managed local records were erased; revocation alone retains the identity record
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: Verify supported signed records against the appropriate public key or DID under an explicit trusted-key policy. The private signing key is needed to create new signatures, not to verify existing signatures. Keep private signing keys protected rather than copying them to verifier machines.

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 or proof semantics. Attestix uses a constrained custom canonical JSON profile with NFC normalization; it does not claim strict RFC 8785 conformance or arbitrary numeric equivalence across languages.

Solution: Use a verifier that supports the documented Attestix credential and canonicalization profile. Check the supported proof and key representation, trusted issuer policy and unsupported-input rejection. Shared fixtures do not establish identical trust or revocation policy across verifiers.

Compliance Issues

Self-assessment blocked for high-risk system

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

This error reflects a configured workflow restriction, not a legal determination. Applicable assessment routes depend on the system, classification, operator role and relevant requirements. Recording an assessment does not establish that the assessor is authorized or that conformity has been achieved. Determine the applicable route separately before recording evidence:

compliance_svc.record_conformity_assessment(
    agent_id=agent_id,
    assessment_type="third_party",  # example only; separately determine the route
    assessor_name="Example assessor - placeholder",
    result="pass",  # example assertion; requires independently reviewed evidence
)

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 a provider-review declaration draft

The compliant field and completion percentage describe workflow records, not legal conformity or certification. Review generated drafts with an accountable provider or assessor.

Blockchain Issues

"No RPC URL configured"

Error: ATTESTIX_BASE_RPC_URL environment variable not set

Solution: Set the Base L2 testnet RPC URL in your environment. Attestix anchors to Base Sepolia today; mainnet support ships once the mainnet schema is registered.

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

Or use a provider like Alchemy:

export ATTESTIX_BASE_RPC_URL="https://base-sepolia.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 testnet ETH on Base Sepolia for gas fees (free from public faucets).

Solution: Fund the wallet associated with ATTESTIX_WALLET_PRIVATE_KEY with testnet ETH on Base Sepolia. Public faucets include the Coinbase Base faucet and the Alchemy Sepolia faucet.

Anchoring is optional

Local identity, credential, governance-evidence and provenance workflows can operate without blockchain anchoring. Network integrations and external status or trust checks have separate connectivity requirements. Omitting anchoring does not establish complete evidence capture or legal conformity.

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)

How do I back up my data?

Back up managed records and protect the signing key if continued signing and issuer continuity are required. Existing signatures can be checked using the corresponding public key under the verifier's trust policy; verification does not require the private signing key. Validate restore behavior separately.

How do I reset everything?

Delete the JSON data files (but NOT .signing_key.json unless you want a completely fresh start). Attestix will recreate empty files on next use.

Getting Help

If your issue is not covered here:

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

On this page