Reference for error codes and messages in CMN tools.

Hypha Errors

Pipeline Error Codes

These codes correspond to stages in the visitor resolution pipeline (sense/taste/spawn/grow/absorb). Each error includes a trace field in the final JSON event showing how far the operation progressed before failure.

Command-Specific Error Codes

Publisher Error Codes

Runtime Diagnostic Codes

Non-fatal diagnostic events emitted during operations. These use the same Agent-First Data protocol structure and are written to the runtime stdout event stream.

Synapse Errors

API Errors

Pulse-Specific Errors

Storage Errors

Error Response Format

Hypha CLI — Error

The nested error.code field contains the specific error code. Parse error.code to branch on error type:

{
  "kind": "error",
  "error": {
    "code": "SIG_FAILED",
    "message": "Core signature verification failed: invalid signature",
    "retryable": false,
    "hint": "read the error field, check hypha --help for the expected input, and retry"
  },
  "trace": {
    "duration_ms": 0
  }
}

{
  "kind": "error",
  "error": {
    "code": "invalid_uri",
    "message": "URI must start with 'cmn://'",
    "retryable": false,
    "hint": "use a CMN URI in the form cmn://domain or cmn://domain/b3.hash"
  },
  "trace": {
    "duration_ms": 0
  }
}

Hypha CLI — Success with Trace

sense returns a trace field with resolution metadata (key fetch, caching, verification):

{
  "kind": "result",
  "result": { "spore": { "..." : "..." } },
  "trace": {
    "uri": "cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2",
    "cmn": { "resolved": true, "cached": true, "public_key": "ed25519.5XmkQ9vZP8nL3xJdFtR7wNcA6sY2bKgU1eH9pXb4" },
    "verified": { "core_signature": true, "capsule_signature": true }
  }
}

Synapse API — Error

{
  "kind": "error",
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Signature verification failed for domain cmn.dev",
    "retryable": false,
    "hint": "verify the signing key and signature before retrying"
  },
  "trace": {
    "storage": "redb"
  }
}

Synapse API — Success

Success responses include a result field with query data and a trace field with internal state:

{
  "kind": "result",
  "result": {
    "query": { "hash": "b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2", "max_depth": 10 },
    "lineage": []
  },
  "trace": {
    "max_depth_reached": false,
    "storage": "redb"
  }
}

Synapse Access Log

Every request produces a protocol-v1 log event. Request fields and optional result/error data live under log; trace merges request metadata with handler-level state.

JSON format (log_format: json):

{
  "kind": "log",
  "log": {
    "method": "GET",
    "path": "/synapse/spore/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2",
    "status_code": 404,
    "error": {
      "code": "NOT_FOUND",
      "message": "Spore not found",
      "retryable": false,
      "hint": "verify the domain/hash and wait for indexing before retrying"
    }
  },
  "trace": {
    "duration_ms": 1
  }
}

Plain format (log_format: plain):

kind=log log.error.code=NOT_FOUND log.error.message="Spore not found" log.error.retryable=false log.method=GET log.path=/synapse/spore/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 log.status_code=404 trace.duration=1ms

The plain format is generated from the same JSON value using agent_first_data::output_plain (logfmt-style key/value output).

Exit Codes

Hypha CLI exit codes:

Debugging

Verbose Output

hypha --verbose taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

Debug Logging

RUST_LOG=debug hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

Trace Logging

RUST_LOG=trace hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

Common Issues

“Key fetch failed”

1. Verify https://yourdomain.com/.well-known/cmn.json is accessible
2. Check that cmn.json contains a valid public_key field
3. Ensure HTTPS is properly configured on the domain

“Signature verification failed”

1. Verify you’re fetching the correct URI
2. Check if publisher updated their public key in cmn.json
3. Try fetching from Synapse mirror if available

“Hash mismatch”

1. Clear cache: hypha cache clean --domain cmn.dev
2. Re-fetch the spore
3. Report to publisher if issue persists

“Local files modified” during grow

Grow detected local changes and refused to overwrite. The error hint shows:

• Old version cache path (from spawned_from)
• New version cache path (run hypha taste <uri> first if not cached)

Compare the two with diff -r <old>/content/ <new>/content/ and apply changes manually.