| Field | Value |
|---|
| Document | MHS-B (normative; tables generated from errors.json) |
| Status | OpenMHS 0.9 development draft (wire revision 1) |
| Editor | The OpenMHS Authors |
| Layer | appendix of the core: the error vocabulary (profiles.md §2) |
| Normative base | core.md §7; MHS-002 §16 |
| Data contract | errors.json (errors.schema.json); error objects: defs.schema.json error (mhs_code pattern ^MHS\.[A-Z]+\.[A-Z0-9_]+$) |
Every failure carries a stable semantic code MHS.<AREA>.<CODE> inside error.data.mhs_code (JSON-RPC errors) or receipt.error.mhs_code (receipt errors). The JSON-RPC numeric code is structural and coarse; the mhs_code is the stable identity that clients, tests and documentation branch on. This appendix is the complete registry of OpenMHS 0.9; the codes belong to wire revision 1 and keep their MHS. prefix. The tables are generated by python3 MHS/sdk/tools/gen_appendices.py from errors.json, which also generates the SDK table in mhs/errors.py; edit the JSON, not the tables.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174.
1. Structure
text
MHS . SAFETY . INTERLOCK_OPEN
│ │ └─ CODE: uppercase, underscores, stable forever
│ └─ AREA: one of the areas in §2
└─ fixed prefix
ERR-001. A code MUST match ^MHS\.[A-Z]+\.[A-Z0-9_]+$ and MUST be listed in this appendix. An endpoint MUST NOT emit an unregistered code; unknown codes are a conformance failure (the client MAY still display them generically, §5).
ERR-002. A code, once published, MUST NOT change meaning and MUST NOT be reused for a different condition. Retired codes stay in this appendix marked retired (MHS-010 GOV-040).
ERR-003. Every error object MUST carry mhs_code, message and data.retryable; a non-retryable error SHOULD carry data.remediation. A validation error SHOULD carry data.details. The error object schema is defs.schema.json $defs.error (closed: no extra fields).
ERR-004. Clients MUST NOT branch on error.message or on the JSON-RPC numeric code for semantics; they MUST branch on mhs_code (MHS-002 PROTO-040). The numeric code exists for JSON-RPC interoperability and transport tooling.
ERR-005. A receipt's error uses the same object and codes as a JSON-RPC error. A physical rejection is a receipt with status: "rejected" and the same mhs_code a JSON-RPC error would carry (MHS-002 PROTO-028); implementations MUST NOT invent a second vocabulary for receipts.
ERR-006. data.retryable MUST be true only when retrying the identical request cannot duplicate a physical effect and cannot bypass a safety check. MHS.OUTCOME.UNKNOWN, any MHS.SAFETY.* rejection and any gated-permit error MUST be retryable: false.
2. Areas and JSON-RPC structural codes
| Area | JSON-RPC code | Codes | Used for |
|---|
PROTOCOL | -32700, -32600, -32601, -32602, -32000 | 9 | Framing, method, parameter, negotiation, batch structure. |
SESSION | -32011 | 6 | Session lifecycle and grants. |
AUTH | -32012 | 7 | Authentication, authorisation, transport security. |
DEVICE | -32013 | 7 | Device identity, readiness, busyness, preconditions. |
RESOURCE | -32014 | 4 | Resource identity and state validation. |
CAPABILITY | -32015 | 6 | Class identity, binding and input/output validation. |
CONFLICT | -32016 | 5 | Idempotency, revision and lease conflicts. |
OUTCOME | -32017 | 3 | Unknown, timeout and aborted outcomes. |
OPERATION | -32018 | 3 | Operation handles and cancellation. |
MODE | -32019 | 4 | Mode declaration, read-only replay, snapshot/restore availability. |
FIDELITY | -32020 | 6 | Fidelity contract, determinism and replay verification. |
LIMIT | -32021 | 6 | Rate, size, concurrency and backpressure limits. |
EVIDENCE | -32022 | 9 | Evidence chain, bundles, signatures and retention. |
SAFETY | -32010 | 13 | Envelope, limits, interlocks, permits, e-stop, risk classes. |
ADAPTER | -32023 | 7 | Adapter manifests, drivers, bridges, shims, licensing. |
REGISTRY | -32024 | 5 | Registry records, trust, federation. |
COMPOSITION | -32025 | 6 | Compositions and their children (reserved profile). |
TRANSPORT | -32026 | 4 | Transport availability and framing failures not covered by PROTOCOL. |
BRIDGE | -32023 | 2 | Declarative binding execution failures. |
HOST | -32027 | 28 | Host-side integration failures: policy, journal, reconciliation and the host evidence ledger (MHS-009). |
INTERNAL | -32603 | 4 | Server faults; never a client error. |
ERR-007. An endpoint MUST use the structural code from this table for the area. Multiple mhs_code values in one area share its structural code; a client that sees an unexpected structural code MUST still read mhs_code and treat the error by area.
3. Registry
Every code has exactly one record in errors.json with the same members: code, area, jsonrpc_code, retryable, status, since, meaning, remediation, driver_subset and, for a deprecated code, replaced_by. Status uses the lifecycle words of capability classes: stable, deprecated (still registered and accepted; emit the replacement), retired or feature (a hello.features disclosure, never an error, §4); active is the pre-0.9 spelling of stable. since is the OpenMHS specification release (spec_version, as MAJOR.MINOR.PATCH) that registered the code with its current meaning; mhs_error_registry versions the registry format and wire revision, not the codes. Remediation is written for the client or agent that receives the error. The Driver column marks the driver subset (§3.22): the only codes a driver or bridge raises itself; every other code is produced by the runtime.
3.1 MHS.PROTOCOL.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.PROTOCOL.PARSE_ERROR | -32700 | no | stable | | The frame is not valid JSON. | Fix framing; send one JSON value per line/message. |
MHS.PROTOCOL.INVALID_REQUEST | -32600 | no | stable | | Not a JSON-RPC 2.0 request (missing jsonrpc, method, bad id). | Send a valid JSON-RPC request. |
MHS.PROTOCOL.METHOD_NOT_FOUND | -32601 | no | stable | | Method unknown or not implemented by this endpoint/profile. | Check hello.features and the profile's method matrix. |
MHS.PROTOCOL.INVALID_PARAMS | -32602 | no | stable | | Params missing or malformed (not an input-schema failure — see CAPABILITY.INPUT_INVALID). | Check the method reference in MHS-002. |
MHS.PROTOCOL.DEADLINE_INVALID | -32602 | no | stable | | Blocking method called without a valid deadline_ms. | Supply deadline_ms ≥ 1. |
MHS.PROTOCOL.VERSION_UNSUPPORTED | -32000 | no | stable | | No mutually supported protocol MAJOR.MINOR. | Upgrade client or connect to an endpoint supporting your version. |
MHS.PROTOCOL.BATCH_NOT_ATOMIC | -32000 | no | stable | | Batch mixes mutations the endpoint cannot order safely. | Split the batch or order the mutations as separate requests. |
MHS.PROTOCOL.BATCH_TOO_LARGE | -32000 | no | stable | | Batch exceeds the advertised maximum. | Split into smaller batches. |
MHS.PROTOCOL.UNSUPPORTED_FEATURE | -32000 | no | stable | | A feature the client requested in hello is not implemented. | Do not request the feature; re-read hello.features. |
3.2 MHS.SESSION.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.SESSION.UNKNOWN | -32011 | no | stable | | session_id does not exist. | Open a session. |
MHS.SESSION.EXPIRED | -32011 | yes | stable | | Session passed expires_at. | Open a new session; re-read state; re-check permits. |
MHS.SESSION.CLOSED | -32011 | no | stable | | Session was closed. | Open a new session. |
MHS.SESSION.CAPABILITY_NOT_GRANTED | -32011 | no | stable | | Capability not in the session grant. | Open a new session requesting the capability (least privilege). |
MHS.SESSION.DEVICE_NOT_GRANTED | -32011 | no | stable | | Device not covered by the session. | Open a session including the device. |
MHS.SESSION.MODE_MISMATCH | -32011 | no | stable | | Requested mode ≠ device mode. | Request the declared mode; never fall back. |
3.3 MHS.AUTH.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.AUTH.UNAUTHENTICATED | -32012 | no | stable | | No or invalid credentials. | Authenticate per the endpoint descriptor's auth. |
MHS.AUTH.TOKEN_EXPIRED | -32012 | yes | stable | | Token expired. | Refresh the token; retry is safe only for reads. |
MHS.AUTH.FORBIDDEN | -32012 | no | stable | | Principal not allowed to perform this action. | Use a principal with the required grant/approval. |
MHS.AUTH.SCOPE_INSUFFICIENT | -32012 | no | stable | | Token scope does not cover the endpoint/device/capability. | Request a narrower-scope-compatible token. |
MHS.AUTH.PRINCIPAL_REQUIRED | -32012 | no | stable | | Operation requires an authenticated principal (human principal for approvals). | Authenticate as the required principal kind. |
MHS.AUTH.TRANSPORT_INSECURE | -32012 | no | stable | | Plaintext transport to a non-loopback endpoint. | Use TLS or a loopback/stdio binding. |
MHS.AUTH.HARDWARE_DISABLED | -32012 | no | stable | | Hardware operation refused because the deployment policy disallows hardware. | Set allow_hardware=true through a trusted operator configuration, or use a simulated endpoint. |
3.4 MHS.DEVICE.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.DEVICE.UNKNOWN | -32013 | no | stable | | device_id not served by this endpoint. | Re-run devices.list. |
MHS.DEVICE.BUSY | -32013 | yes | stable | yes | Exclusive capability is held by another operation. | Wait for the operation to finish or cancel it; retry with backoff. |
MHS.DEVICE.OFFLINE | -32013 | yes | stable | | Device is unreachable or powered down. | Bring it online; check the adapter's lifecycle state. |
MHS.DEVICE.NOT_READY | -32013 | yes | stable | | Device initialising; commands not accepted yet. | Retry after readiness (hello). |
MHS.DEVICE.FAULTED | -32013 | no | stable | yes | Device reports a fault state. | Clear the fault (self-test/reset) before further commands. |
MHS.DEVICE.PRECONDITION_UNMET | -32013 | no | stable | yes | A declared physical precondition is false (tip attached, plate present, homed). | Satisfy the precondition, then retry. |
MHS.DEVICE.FAILED | -32013 | no | stable | | Device reported a terminal failure unrelated to the request shape. | Observe state, recover the device, then re-plan. |
3.5 MHS.RESOURCE.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.RESOURCE.UNKNOWN | -32014 | no | stable | | resource_id not present on the device. | Re-read devices.get. |
MHS.RESOURCE.FIELD_UNKNOWN | -32014 | no | stable | | Write/read referenced a field not in the resource state schema. | Use declared fields only. |
MHS.RESOURCE.NOT_WRITABLE | -32014 | no | stable | | Resource does not accept writes. | Use a capability of verb invoke/write. |
MHS.RESOURCE.STATE_INVALID | -32014 | no | stable | | Resource state failed its own schema (driver bug). | Report to the adapter maintainer; do not retry blindly. |
3.6 MHS.CAPABILITY.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.CAPABILITY.UNKNOWN | -32015 | no | stable | | Class id not implemented by this endpoint/device. | Re-read the manifest; check class MAJOR. |
MHS.CAPABILITY.NOT_BOUND | -32015 | no | stable | | Class known but not bound to this device/resource. | Use a bound capability. |
MHS.CAPABILITY.KIND_MISMATCH | -32015 | no | stable | | Binding resource kind is not in the class resource_kinds. | Adapter defect; report it. |
MHS.CAPABILITY.INPUT_INVALID | -32015 | no | stable | yes | Input failed the binding/class JSON Schema. | Fix the input; data.details.errors[] lists violations. |
MHS.CAPABILITY.OUTPUT_INVALID | -32015 | no | stable | yes | Native result did not produce a valid capability output. | Adapter/shim defect; the receipt is failed. |
MHS.CAPABILITY.EXPERIMENTAL_PRESENT | — | — | feature | | Not an error: feature marker that an experimental class is bound. | Treat experimental classes as unstable. |
3.7 MHS.CONFLICT.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.CONFLICT.REVISION | -32016 | no | stable | | expected_revision ≠ current revision. | Read state, re-plan, retry with the current revision. |
MHS.CONFLICT.COMMAND_ID_REUSE | -32016 | no | stable | | command_id reused with a different input digest. | Use a new ULID for a new command. |
MHS.CONFLICT.LEASE_CONFLICT | -32016 | yes | stable | | Concurrency lease is held by another operation. | Wait for release; do not force. |
MHS.CONFLICT.SNAPSHOT_MISMATCH | -32016 | no | stable | | Snapshot does not belong to the target device/instance. | Take a snapshot from this device. |
MHS.CONFLICT.STATE_HASH | -32016 | no | stable | | Declared state hash does not recompute from the supplied state document. | Recapture the state/snapshot; do not trust the hash. |
3.8 MHS.OUTCOME.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.OUTCOME.UNKNOWN | -32017 | no | stable | | Effect may have occurred; outcome not observable. | Observe state and the retained receipt; never retry blindly. |
MHS.OUTCOME.TIMEOUT | -32017 | no | stable | yes | Deadline exceeded; the effect may be in flight, so observe state first. | Observe state; retry only idempotently with the same command_id. |
MHS.OUTCOME.ABORTED | -32017 | no | stable | yes | Operation aborted by a device-level event (power loss, watchdog). | Recover device state, then re-plan. |
3.9 MHS.OPERATION.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.OPERATION.UNKNOWN | -32018 | no | stable | | operation_id not known (or retention expired). | Use operations.list; retain receipts. |
MHS.OPERATION.NOT_CANCELLABLE | -32018 | no | stable | | Capability is declared non-cancellable. | Use mhs.safety.estop for emergencies. |
MHS.OPERATION.ALREADY_FINISHED | -32018 | no | stable | | Operation reached a terminal state. | Read the final receipt; no cancellation needed. |
3.10 MHS.MODE.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.MODE.READ_ONLY | -32019 | no | stable | | Mutation attempted in replay mode. | Replay is read-only; use the source endpoint for live actions. |
MHS.MODE.SNAPSHOT_UNSUPPORTED | -32019 | no | stable | | Device does not support snapshots. | Check fidelity.snapshot_restore. |
MHS.MODE.RESTORE_UNSUPPORTED | -32019 | no | stable | | Device/snapshot cannot be restored (hardware or unsupported). | Use a simulator with snapshot support. |
MHS.MODE.SWITCH_FORBIDDEN | -32019 | no | stable | | A mode change was attempted on a live session/device. | Open a session on the device with the correct declared mode. |
3.11 MHS.FIDELITY.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.FIDELITY.CONTRACT_REQUIRED | -32020 | no | stable | | Simulated/hybrid device lacks a valid fidelity contract. | Fix the manifest; a simulator without a contract is CL0 only. |
MHS.FIDELITY.SEED_REQUIRED | -32020 | no | stable | | Deterministic replay claimed but no seed supplied on reset. | Call world.reset with a seed. |
MHS.FIDELITY.REPLAY_DIVERGENCE | -32020 | no | stable | | Replay state hashes diverged from the recording. | Treat the replay claim as invalid; investigate the model/seed. |
MHS.FIDELITY.GAP_UNDISCLOSED | -32020 | no | stable | | Host/endpoint detected a known gap not shown to the agent. | Disclose gaps before actuation. |
MHS.FIDELITY.DETERMINISM_UNSUPPORTED | -32020 | no | stable | | Requested determinism-based operation on a statistical/none device. | Use repeated trials, not replay equality. |
MHS.FIDELITY.VALIDATION_MISSING | -32020 | no | stable | | F3 claimed without a validation record. | Provide or downgrade to F2. |
3.12 MHS.LIMIT.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.LIMIT.BACKPRESSURE | -32021 | yes | stable | | Consumer cannot keep up; buffering would be unbounded. | Slow down, reduce rate_hz, resume from a gap/state read. |
MHS.LIMIT.RATE_EXCEEDED | -32021 | yes | stable | | Rate limit exceeded. | Wait data.details.retry_after_ms; batch or reduce rate. |
MHS.LIMIT.SUBSCRIPTION_LIMIT | -32021 | no | stable | | Max concurrent subscriptions reached. | Close a subscription first. |
MHS.LIMIT.OPERATION_LIMIT | -32021 | no | stable | | Max concurrent operations reached. | Finish/cancel operations; wait. |
MHS.LIMIT.PAYLOAD_TOO_LARGE | -32021 | no | stable | | Frame/request exceeds the size limit. | Reduce payload; use artifact references for large data. |
MHS.LIMIT.CONNECTION_LIMIT | -32021 | yes | stable | | Too many concurrent connections. | Close idle connections; reconnect with backoff. |
3.13 MHS.EVIDENCE.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.EVIDENCE.CHAIN_BROKEN | -32022 | no | stable | | Receipt chain does not recompute. | Re-export from the endpoint; investigate tampering. |
MHS.EVIDENCE.SIGNATURE_INVALID | -32022 | no | stable | | Detached JWS does not verify or key unknown/revoked. | Treat as unsigned; resolve the key in the registry. |
MHS.EVIDENCE.TRUNCATED | -32022 | no | stable | | History was truncated by retention; marker present. | Continue from first_retained_seq; do not assume continuity. |
MHS.EVIDENCE.UNKNOWN | -32022 | no | stable | | Bundle/endpoint evidence not available. | Check include_telemetry/retention; export a smaller range. |
MHS.EVIDENCE.EXPORT_TOO_LARGE | -32022 | yes | stable | | Export would exceed the advertised size. | Page with since_receipt. |
MHS.EVIDENCE.RETENTION_EXCEEDED | -32022 | no | stable | | Requested receipt is outside retention. | Use the oldest retained receipt or the truncated marker. |
MHS.EVIDENCE.SCHEMA_INVALID | -32022 | no | stable | | A receipt in the evidence bundle violates receipt.schema.json. | Re-export from the endpoint and investigate the producer. |
MHS.EVIDENCE.SCHEMA_UNAVAILABLE | -32022 | no | stable | | Receipt schemas were unavailable, so schema verification could not complete. | Install the MHS schema set and verify again; do not treat as validated. |
MHS.EVIDENCE.SIGNATURE_UNVERIFIABLE | -32022 | yes | stable | | A detached signature exists but no key resolver is available. | Resolve the signing key through the registry and verify offline. |
3.14 MHS.SAFETY.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.SAFETY.INTERLOCK_OPEN | -32010 | no | stable | yes | A required interlock reads open. | Close/clear the interlock, then reset if latched. |
MHS.SAFETY.ENVELOPE_VIOLATION | -32010 | no | stable | yes | Input outside declared limits/allowed values. | Adjust the input to the declared envelope. |
MHS.SAFETY.CUMULATIVE_LIMIT | -32010 | no | stable | | Cumulative budget (time/travel/volume/dose) exhausted. | Wait for the window to reset or obtain a new authorization. |
MHS.SAFETY.PERMIT_INVALID | -32010 | no | stable | | Missing, expired, consumed or mismatched permit. | Obtain a permit for exactly this input via approval. |
MHS.SAFETY.APPROVAL_REQUIRED | -32010 | no | stable | | Human approval required (R3, R2 policy, human presence). | Collect the required approval; retry with permit. |
MHS.SAFETY.RESET_REFUSED | -32010 | no | stable | | Reset while interlock open/unknown or not latched. | Clear interlocks; reset only a latched device. |
MHS.SAFETY.SAFE_STATE_UNREACHED | -32010 | no | stable | yes | Device could not reach the declared safe state in time. | Use the physical e-stop; inspect the device. |
MHS.SAFETY.ESTOP_ENGAGED | -32010 | no | stable | yes | Device is e-stopped/latched and refuses actuation. | Reset after clearing interlocks; issue a new start command. |
MHS.SAFETY.RISK_CLASS_BLOCKED | -32010 | no | stable | | Session/action not permitted at the device's risk class. | Use an authorized session with the required approvals. |
MHS.SAFETY.NOT_CERTIFIED | — | — | feature | | Not an error: mandatory hello.features disclosure. | Display it; never treat MHS as a safety channel. |
MHS.SAFETY.ESTOP_UNAVAILABLE | -32010 | no | stable | | The endpoint exposes no software e-stop path for this device. | Use the hardware e-stop; software conformance never replaces it. |
MHS.SAFETY.SAFE_STATE | -32010 | no | stable | | A safe-state attempt failed or could not be verified. | Inspect safety.status and the bridge stop path. |
MHS.SAFETY.LIMITS_UNSET | -32010 | no | stable | yes | A hardware or hybrid write/invoke at risk R1 or above has a numeric input with no declared limit, or a limit declared operator_required that no operator overlay fills. | Declare a sourced limit in the driver or have the operator supply site-limits.json; never invent a bound. |
3.15 MHS.ADAPTER.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.ADAPTER.MANIFEST_INVALID | -32023 | no | stable | | Adapter manifest/bindings fail schema or reference checks. | Fix the manifest; see data.details.errors[]. |
MHS.ADAPTER.LICENSE_BLOCKED | -32023 | no | stable | | Upstream licence incompatible with use/redistribution. | Change use, obtain a licence, or do not use the adapter. |
MHS.ADAPTER.SOURCE_UNPINNED | -32023 | no | stable | | Runnable adapter has no pinned source commit. | Pin source.commit and regenerate evidence. |
MHS.ADAPTER.BRIDGE_UNAVAILABLE | -32023 | yes | stable | | Bridge runtime/dependency not installed. | Run runtime.install; check the lifecycle. |
MHS.ADAPTER.SHIM_FAILED | -32023 | no | stable | yes | Shim raised or returned an uninterpretable result. | Inspect the redacted message; fix the shim; do not report success. |
MHS.ADAPTER.NATIVE_SYMBOL_MISSING | -32023 | no | stable | | Declared native symbol does not exist at runtime. | Fix the binding; mark stability: fragile if private. |
MHS.ADAPTER.CONTRACT_MISMATCH | -32023 | no | stable | | Served manifest differs from the adapter declaration. | Regenerate from the adapter; report drift. |
3.16 MHS.REGISTRY.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.REGISTRY.UNAVAILABLE | -32024 | yes | stable | | Registry not reachable. | Use a local mirror; retry with backoff. |
MHS.REGISTRY.RECORD_INVALID | -32024 | no | stable | | Record fails its schema or reference checks. | Fix the record; re-publish. |
MHS.REGISTRY.SIGNATURE_INVALID | -32024 | no | stable | | Record/claim signature invalid or key revoked. | Treat as unsigned; resolve keys. |
MHS.REGISTRY.FEDERATION_FAILED | -32024 | yes | stable | | A federated peer failed; partial results. | Retry if require_all_peers; otherwise use partial results. |
MHS.REGISTRY.CLAIM_INVALID | -32024 | no | stable | | Claim does not match its report (subject/profile/level/digest). | Re-run the suite and re-issue the claim. |
3.17 MHS.COMPOSITION.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.COMPOSITION.UNKNOWN | -32025 | no | stable | | composition_ref does not resolve. | Publish/serve the composition document. |
MHS.COMPOSITION.INVALID | -32025 | no | stable | | Composition document invalid or exceeds session grants. | Fix the composition; request the needed grants. |
MHS.COMPOSITION.CYCLE | -32025 | no | stable | | Composition includes itself (directly or transitively). | Remove the cycle. |
MHS.COMPOSITION.CHILD_FAILED | -32025 | no | stable | | A child receipt failed and the composition stops on failure. | Inspect the embedded child receipt. |
MHS.COMPOSITION.CANCELLED | -32025 | no | stable | | The composition was cancelled. | Inspect child safe-state results. |
MHS.COMPOSITION.GRANT_EXCEEDED | -32025 | no | stable | | A child requested a capability beyond the session grants. | Open a session with the required grants; compositions cannot escalate. |
3.18 MHS.TRANSPORT.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.TRANSPORT.UNAVAILABLE | -32026 | yes | stable | | Transport cannot connect. | Check the endpoint address/process; retry with backoff. |
MHS.TRANSPORT.CLOSED | -32026 | yes | stable | | Connection closed by the peer. | Reconnect; re-read state; never retry unknown outcomes blindly. |
MHS.TRANSPORT.TLS_REQUIRED | -32026 | no | stable | | TLS required but not negotiated. | Use TLS. |
MHS.TRANSPORT.PROTOCOL_ERROR | -32026 | no | stable | | Framing error not covered by MHS.PROTOCOL.* (e.g. SSE corruption). | Fix the transport; reconnect. |
3.19 MHS.BRIDGE.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.BRIDGE.CAPABILITY_NOT_SUPPORTED | -32023 | no | stable | | The bridge does not implement the requested capability. | Inspect the adapter manifest; declare the capability unsupported or add a mapping. |
MHS.BRIDGE.MAPPING_ERROR | -32023 | no | stable | | A declarative binding mapping could not be applied. | Fix the binding; unmapped values are never guessed. |
3.20 MHS.HOST.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.HOST.CAPABILITY_REQUIRED | -32027 | no | stable | | A capability id is required for this host operation. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.CONFIG_REQUIRED | -32027 | no | stable | | A trusted MHS host configuration file is required. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.DEVICE_AMBIGUOUS | -32027 | no | stable | | The device is ambiguous; bind it explicitly in policy. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.DEVICE_NOT_ALLOWED | -32027 | no | stable | | The device is not on the trusted host allow-list. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.DEVICE_NOT_FOUND | -32027 | no | stable | | The requested device is unknown to the host. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.DEVICE_REQUIRED | -32027 | no | stable | | A device id is required for this host operation. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.ENDPOINT_NOT_ALLOWED | -32027 | no | stable | | The endpoint is not on the trusted host allow-list. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.ENDPOINT_UNAVAILABLE | -32027 | no | stable | | The configured endpoint could not be reached. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.EVIDENCE_EXPORT_FAILED | -32027 | no | stable | | The endpoint evidence bundle could not be exported. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.EVIDENCE_WRITE_FAILED | -32027 | no | stable | | The durable host evidence store could not be written. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.HARDWARE_GATED | -32027 | no | stable | | The host requires allow_hardware=true for this hardware call. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.INVALID_ARGUMENT | -32027 | no | stable | | The host call arguments are invalid. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.NO_CAPABILITIES | -32027 | no | stable | | The endpoint exposes no callable capability for the host policy. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.NO_ENDPOINTS | -32027 | no | stable | | No MHS endpoint is configured for the host. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.NO_READ_CAPABILITY | -32027 | no | stable | | The device exposes no read capability for reconciliation. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.NO_RESOURCES | -32027 | no | stable | | The device exposes no resource to read. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.OPENAI4S_MISSING | -32027 | no | deprecated → MHS.HOST.ADAPTER_MISSING | | Deprecated alias of MHS.HOST.ADAPTER_MISSING (the OpenAI4S host package is not importable). | The OpenAI4S host package (its MCP client) is not importable in the host process: install OpenAI4S in that environment or add its source tree to PYTHONPATH, or disable the OpenAI4S integration, then retry. Handle it exactly like MHS.HOST.ADAPTER_MISSING, which replaces this deprecated alias in 0.10. |
MHS.HOST.OPERATION_NOT_FOUND | -32027 | no | stable | | The host operation id is unknown. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.OPERATION_REQUIRED | -32027 | no | stable | | An operation id is required for reconciliation. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.PROTOCOL_ERROR | -32027 | no | stable | | The host received an invalid MCP/MHS protocol response. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.READ_FAILED | -32027 | no | stable | | The host could not read device state for reconciliation. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.RECONCILE_REQUIRED | -32027 | no | stable | | A prior ambiguous outcome must be reconciled before a new command. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.SDK_MISSING | -32027 | no | stable | | The MHS SDK is not importable in the host environment. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.SESSION_FAILED | -32027 | no | stable | | The host could not open an MHS session. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.TOOL_ERROR | -32027 | no | stable | | An MCP tool call failed at the host boundary. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.UNEXPECTED | -32027 | no | stable | | An unexpected host integration failure occurred. | Inspect the host policy/configuration and retry after fixing it. |
MHS.HOST.ADAPTER_MISSING | -32027 | no | stable | | The host-integration package for the configured host is not importable. | Install the host integration package in the host environment, or disable the integration. |
MHS.HOST.JOURNAL_CORRUPT | -32027 | no | stable | | The host's durable command journal is unreadable or fails its integrity check; the affected record is never skipped. | Repair or restore the journal and reconcile pending commands before issuing new ones. |
3.21 MHS.INTERNAL.*
| Code | JSON-RPC | Retryable | Status | Driver | Meaning | Remediation |
|---|
MHS.INTERNAL.ERROR | -32603 | no | stable | | Unexpected server fault. | Report with the request id; do not retry mutations. |
MHS.INTERNAL.NOT_IMPLEMENTED | -32603 | no | stable | | Code path not implemented (endpoint defect). | Implement or avoid; report to maintainer. |
MHS.INTERNAL.OVERLOADED | -32603 | yes | stable | | Server overloaded (queue full). | Retry with backoff. |
MHS.INTERNAL.SCHEMA_DRIFT | -32603 | no | stable | | Served schema differs from validated schema. | Restart/regenerate endpoint; report adapter defect. |
3.22 Driver subset
These 13 codes are the complete vocabulary a driver or bridge raises (mhs.signals.DriverFailed(code, message)); the runtime produces every other code. A driver that cannot classify a native failure raises any other exception, which the runtime reports as MHS.ADAPTER.SHIM_FAILED with a redacted message.
| Code | Raised when |
|---|
MHS.DEVICE.BUSY | Exclusive capability is held by another operation. |
MHS.DEVICE.FAULTED | Device reports a fault state. |
MHS.DEVICE.PRECONDITION_UNMET | A declared physical precondition is false (tip attached, plate present, homed). |
MHS.CAPABILITY.INPUT_INVALID | Input failed the binding/class JSON Schema. |
MHS.CAPABILITY.OUTPUT_INVALID | Native result did not produce a valid capability output. |
MHS.OUTCOME.TIMEOUT | Deadline exceeded; the effect may be in flight, so observe state first. |
MHS.OUTCOME.ABORTED | Operation aborted by a device-level event (power loss, watchdog). |
MHS.SAFETY.INTERLOCK_OPEN | A required interlock reads open. |
MHS.SAFETY.ENVELOPE_VIOLATION | Input outside declared limits/allowed values. |
MHS.SAFETY.SAFE_STATE_UNREACHED | Device could not reach the declared safe state in time. |
MHS.SAFETY.ESTOP_ENGAGED | Device is e-stopped/latched and refuses actuation. |
MHS.SAFETY.LIMITS_UNSET | A hardware or hybrid write/invoke at risk R1 or above has a numeric input with no declared limit, or a limit declared operator_required that no operator overlay fills. |
MHS.ADAPTER.SHIM_FAILED | Shim raised or returned an uninterpretable result. |
3.23 Deprecated codes
A deprecated code stays registered for its deprecation window; endpoints emit the replacement and clients treat both alike.
| Code | Replaced by |
|---|
MHS.HOST.OPENAI4S_MISSING | MHS.HOST.ADAPTER_MISSING |
4. Cross-reference: codes that are also feature strings
Three identifiers are not errors and MUST NOT be emitted in an error object; they are advertised in hello.features and endpoint descriptor features[]:
| Feature | Meaning | Where |
|---|
MHS.SAFETY.NOT_CERTIFIED | Mandatory disclosure that OpenMHS is not a safety certification. | MHS-004 SAFE-050. |
MHS.CAPABILITY.EXPERIMENTAL_PRESENT | An experimental capability class is bound by this endpoint. | MHS-003 CAP-005. |
replay.seek | Replay endpoint supports revision seeking. | MHS-005 FID-024. |
ERR-008. An endpoint MUST NOT use an error code as a feature marker or a feature string as an error mhs_code; the two vocabularies are disjoint except for the three documented disclosures above, which are only features.
5. Client handling of unknown codes
ERR-009. A client that receives an unregistered MHS.<AREA>.<CODE> MUST treat it as a non-retryable error of that area, display the code and message, and MUST NOT map it to success or to a generic "unknown" that loses the area. Area-level behaviour is stable; code-level additions are MINOR changes.
ERR-010. A client MUST NOT retry when data.retryable is absent. Absence is treated as false; the endpoint is non-conformant for omitting it.
6. Adding a code
ERR-011. A new code requires an accepted RFC (MHS-010 §2), a record in errors.json (this appendix is regenerated from it), a conformance test for the condition, and a MINOR version bump of the document set and suite. Deletion/retirement follows the deprecation windows of MHS-010 §5.
ERR-012. The code string and its meaning are part of the stable API surface: renaming a code is prohibited; introduce a new code and retire the old one.
7. Requirements list (this appendix)
ERR-001 Codes match the grammar and are registered here. ERR-002 Stable meaning; no reuse. ERR-003 mhs_code, message, data.retryable mandatory; remediation advised. ERR-004 Branch on mhs_code, not message or numeric code. ERR-005 Receipt errors use the same objects/codes. ERR-006 Retryable only when safe; unknown/safety never retryable. ERR-007 Structural code per area. ERR-008 Feature strings and error codes are disjoint vocabularies. ERR-009 Unknown codes handled by area, non-retryable. ERR-010 Missing retryable means not retryable. ERR-011 New codes via RFC + test + MINOR bump. ERR-012 No renaming; new code + retirement instead.