Troubleshooting and FAQ¶

Common errors¶

ModuleNotFoundError: No module named 'aevum.core'¶

The virtual environment is not active, or Aevum is not installed in the current environment.

# Verify which Python is running
python -c "import sys; print(sys.executable)"

# Install in the current environment
pip install aevum-core

# Verify
python -c "import aevum.core; print('ok')"

On Linux/macOS, activate your virtual environment first:

source .venv/bin/activate

On Windows (PowerShell):

.venv\Scripts\Activate.ps1

This is a warning, not an error. Cedar is an optional dependency. The five absolute barriers still fire unconditionally.

To install Cedar:

pip install "aevum-core[cedar]"

status="error", error_code="consent_required"¶

Your agent does not have an active consent grant for this operation.

Common causes: - The grant does not include the operation (e.g., "replay" is not in the operations list) - The grant has expired (check expires_at) - The grant was revoked (check revocation_status) - The subject_id in the call does not match the subject_id in the grant - The purpose in the call does not match the purpose in the grant - The actor (used as grantee_id) does not match the grant's grantee_id

# Inspect the ConsentGrant object you created:
print("grantee_id:", grant.grantee_id)
print("operations:", grant.operations)
print("expires_at:", grant.expires_at)
print("purpose:   ", grant.purpose)
print("subject_id:", grant.subject_id)

# Confirm the grant is in the ledger:
print("ledger count:", engine.ledger_count())

KeyError: 'replayed_payload' on engine.replay()¶

The replay call is returning status="error", not status="ok". Always check result.status before accessing result.data:

r = engine.replay(audit_id="urn:aevum:audit:...", actor="my-agent")
if r.status == "ok":
    print(r.data["replayed_payload"])
else:
    print("Replay failed:", r.data)

Common cause: the actor does not have a consent grant that includes "replay" in the operations list.

status="error", error_code="provenance_required"¶

The provenance dict is missing or has no source_id.

# This fails:
engine.ingest(
    data={...},
    provenance={},  # no source_id
    ...
)

# Fix:
engine.ingest(
    data={...},
    provenance={
        "source_id": "my-system",           # required
        "chain_of_custody": ["my-system"],   # recommended
        "classification": 0,                 # required
    },
    ...
)

status="crisis"¶

The ingested payload contains a crisis keyword (suicidal ideation, immediate physical danger, medical emergency).

This is Barrier 1 firing correctly. The data was not ingested.

The result.data["safe_message"] and result.data["resources"] fields contain text appropriate to present to the user.

If the keyword triggered incorrectly (false positive), open an issue on GitHub with the specific phrase and context.

aevum: command not found (Windows)¶

The Python Scripts directory is not on your PATH. Use the module form instead:

python -m aevum.cli version
python -m aevum.cli --help

To fix permanently (PowerShell):

$p = python -c "import sys; print(sys.exec_prefix)"
[Environment]::SetEnvironmentVariable(
    "PATH",
    [Environment]::GetEnvironmentVariable("PATH", "User") + ";$p\Scripts",
    "User"
)

Restart your terminal after running this.

engine.verify_sigchain() returns False¶

The sigchain integrity check failed. This means either: - A ledger entry was modified after it was written - The Ed25519 signing key changed between events without proper key rotation

Steps to diagnose:

events = engine.get_ledger_entries()
for e in events:
    print(e["sequence"], e["audit_id"], e["event_type"], e["actor"])
# The last valid event is the one before the chain breaks

Note which audit_id is the last valid event
Check whether a key rotation occurred (signer_key_id field)
If using a persistent store, check for direct database modifications
Open a GitHub Issue with the specific audit_id if you cannot identify the cause

PostgreSQL: "column does not exist" or schema errors¶

Run the database migration:

aevum store migrate --dsn postgresql://user:password@host:5432/aevum

OPA sidecar: all operations returning error¶

OPA is configured (AEVUM_OPA_URL is set) but not reachable. Aevum fails closed — any OPA error results in a denial.

# Check OPA is running
curl http://your-opa-host:8181/health

# Check the policy
curl http://your-opa-host:8181/v1/data/aevum/authz/allow \
  -d '{"input": {"principal": "test", "action": "query", "resource": {}}}' \
  -H "Content-Type: application/json"

Expected: {"result": true} for a permissive policy.

If OPA is not reachable, unset AEVUM_OPA_URL to use Cedar only:

unset AEVUM_OPA_URL

ValidationError: purpose must be specific¶

Aevum rejects generic purpose values:

# These raise ValidationError:
ConsentGrant(..., purpose="any")
ConsentGrant(..., purpose="all")
ConsentGrant(..., purpose="")

# Use a specific, auditable purpose:
ConsentGrant(..., purpose="billing-inquiry")
ConsentGrant(..., purpose="care-coordination")

Still stuck?¶

Open an issue on GitHub Issues with: 1. The error message and traceback 2. The Python version (python --version) 3. The aevum-core version (python -c "import aevum.core; print(aevum.core.__version__)") 4. Minimal code that reproduces the issue

Installation questions¶

Does Aevum send any data outside my environment?

No. By default, nothing leaves your process. Optional complications (aevum-oidc, aevum-llm) make outbound calls only when configured.

Do I need a database to use Aevum?

No. The default Engine() uses in-memory storage. For persistence, add aevum-store-oxigraph (embedded) or aevum-store-postgres.

Is Aevum a SaaS product?

No. It is a Python library. You install it and run it yourself. Your data never leaves your infrastructure.

Can I run Aevum on a Raspberry Pi or other low-powered hardware?

Yes. With Oxigraph as the backend and no OPA sidecar, the memory and CPU footprint is minimal. The sigchain operations (Ed25519, SHA3-256) are fast on any modern hardware including ARM.

Does aevum-mcp only work with Claude Desktop?

No. It works with any MCP-compatible host — Claude Desktop, Cursor, VS Code Copilot, and others. The configuration format is the same. See MCP Setup.

How do I migrate from Oxigraph to PostgreSQL?

aevum store migrate --from oxigraph:/path --to postgres:postgresql://...

This migrates the knowledge graph, consent ledger, and episodic ledger.

Can I use Aevum without a consent grant?

No. Barrier 3 (Consent) blocks ingest, query, and replay without an active consent grant. This is unconditional.

What happens if I don't have cedarpy installed?

The kernel warns at startup and falls back to permissive consent decisions. The five absolute barriers still fire unconditionally — crisis detection, classification ceiling, consent (fast-path denials), audit immutability, and provenance are not affected.

How do I handle GDPR right-to-erasure?

Call engine.revoke_consent_grant(grant_id). The data in the knowledge graph becomes immediately unreachable at the next operation. Physical deletion from the storage backend is a separate step if required by your data retention policy.

Can multiple agents share the same Engine instance?

Yes, with different grantee_id values in their consent grants. Each agent's access is scoped to its own grants.

What is a "complication"?

Aevum's word for a policy-governed extension. Not a plugin, not a module — a complication. Each complication goes through a 7-state lifecycle (DISCOVERED → PENDING → APPROVED → ACTIVE → SUSPENDED → DEPRECATED → REMOVED) and is logged to the episodic ledger at every state transition.

Sigchain and audit questions¶

Does Aevum have an SLA?

No. It is open source software. Community support via GitHub Issues and GitHub Discussions. Commercial support is on the roadmap.

What is the difference between replay and query?

query retrieves current data from the knowledge graph (urn:aevum:knowledge). replay reconstructs a past ledger entry from the provenance graph (urn:aevum:provenance). They read from different places and return different things. See The Five Functions for the full distinction.