Error Codes

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 code field contains the specific error code. Parse code to branch on error type:

{
  "code": "SIG_FAILED",
  "error": "Core signature verification failed: invalid signature",
  "trace": {
    "duration_ms": 0
  }
}

{
  "code": "invalid_uri",
  "error": "URI must start with 'cmn://'",
  "trace": {
    "duration_ms": 0
  }
}

Hypha CLI — Success with Trace

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

{
  "code": "ok",
  "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

{
  "code": "error",
  "error": "Signature verification failed for domain cmn.dev",
  "trace": {
    "error_code": "SIGNATURE_INVALID",
    "storage": "redb"
  }
}

Synapse API — Success

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

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

Synapse Access Log

Every request produces a single access log line using Agent-First Data fields at the top level (code, request fields, optional result/error, and trace). The trace field merges request metadata with handler-level state.

JSON format (log_format: json):

{
  "code": "request",
  "method": "GET",
  "path": "/synapse/spore/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2",
  "status_code": 404,
  "error": "Spore not found",
  "trace": {
    "duration_ms": 1,
    "error_code": "NOT_FOUND"
  }
}

Plain format (log_format: plain):

code=request method=GET path=/synapse/spore/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 status_code=404 error="Spore not found" trace.duration=1ms trace.error_code=NOT_FOUND

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

“Merge conflict” during grow

1. Resolve conflicts in affected files
2. git add <resolved-files>
3. git commit
4. Your spore.core.json is preserved automatically