Error Codes

DSM exceptions expose stable machine-readable error codes through DsmException.errorCode(). Use the exception type to identify the failure domain and the code to drive retry policy, metrics, logs, and alert routing.

Code Categories

Range	Domain	Typical exception surface	Operator meaning
`DSM-0xxx`	Runtime lifecycle / fallback	`DsmException`	Runtime state or uncategorized DSM failure.
`DSM-1xxx`	Configuration	`DsmConfigurationException`	Bad runtime, collection, codec, lease, or secret configuration.
`DSM-2xxx`	Security	`DsmSecurityException`	HMAC, nonce, key version, admission, encryption, or sender ban failure.
`DSM-3xxx`	Consistency	`DsmConsistencyException`	Owner verify, conflict resolver, migration, or eviction consistency boundary.
`DSM-4xxx`	Sync protocol	`SyncProtocolException`	Wire payload, snapshot, replay, or delta protocol violation.
`DSM-5xxx`	Transport	`DsmTransportException`	Connection or send failure.
`DSM-6xxx`	Codec	`CodecException`	Serialization, deserialization, record codec, or schema fingerprint failure.
`DSM-7xxx`	Migration	`DsmMigrationException`	Migration timeout or conflicting ownership lineage.
`DSM-8xxx`	Lease and fencing	Lease/fencing exceptions	Stale holder, quorum unavailable, or fencing rejection.
`DSM-9xxx`	Change streams	`ChangeStreamOverflowException`	Bounded change stream overflow or backpressure surface.

High-Signal Codes

Code	Name	Meaning	First action
`DSM-0001`	`RUNTIME_START_STATE_INVALID`	Runtime start was requested from an invalid lifecycle state.	Check startup ordering and duplicate lifecycle calls.
`DSM-1001`	`DUPLICATE_COLLECTION_LOCATOR`	Two collections tried to register the same locator.	Fix bootstrap configuration or dynamic registration ownership.
`DSM-1003`	`SERVICE_ID_REQUIRED`	Runtime builder could not resolve a service ID.	Set `dsm.service-id` or builder `serviceId(...)`.
`DSM-1017`	`LEASE_RENEW_SKEW_INVALID`	Lease renew skew is not smaller than the lease term.	Fix lease timing properties.
`DSM-2001`	`HMAC_INVALID`	Secure envelope signature failed.	Treat as security signal; check shared secret and possible tampering.
`DSM-2006`	`SECURITY_ENCRYPTION_REQUIRED`	Node requiring encryption received plaintext.	Check mixed-mode rollout and encryption settings.
`DSM-2007`	`SECURITY_SENDER_BANNED`	Sender exceeded verification failure threshold.	Inspect sender identity and failed auth rate.
`DSM-2008`	`KEY_VERSION_BELOW_MINIMUM`	Envelope key version is below local minimum.	Check key rotation rollout.
`DSM-3004`	`CONFLICT_RESOLVER_NOT_COMMUTATIVE`	Custom resolver produced different winners for `(A, B)` and `(B, A)`.	Fix resolver before production rollout.
`DSM-3005`	`CONFLICT_RESOLVER_INVALID_METADATA`	Merged entity did not carry valid lineage metadata.	Preserve or construct valid `EntityMetadata` in resolver output.
`DSM-4002`	`WIRE_VERSION_INCOMPATIBLE`	Peer advertised unsupported wire version.	Check rolling upgrade window.
`DSM-6003`	`SCHEMA_INCOMPATIBLE`	Record codec fingerprint mismatch.	Align entity record schemas across nodes.
`DSM-8001`	`FENCING_REJECTED`	Stale holder attempted a fenced side effect.	Stop stale worker path and inspect lease lineage.
`DSM-8002`	`QUORUM_UNAVAILABLE`	QUORUM lease cannot prove safe majority.	Inspect membership stability and visible peer count.
`DSM-9001`	`CHANGE_STREAM_OVERFLOW`	Change stream buffer overflowed under `ERROR` policy.	Tune consumer speed, buffer size, or overflow policy.

Handling Guidance

Category	Retry?	Escalate?	Notes
Configuration	no	yes	Fail fast; retries hide a bad deployment.
Security	no by default	yes	Do not log secrets, HMACs, nonce values, or decrypted payloads.
Consistency	depends	yes	Resolve the ownership, resolver, or schema cause before retrying side effects.
Sync protocol	usually no	yes	Protocol mismatches indicate bad rollout, corrupt payload, or incompatible peer.
Transport	yes with backoff	maybe	Retry only if the operation is idempotent or guarded by lineage/fencing.
Codec	no	yes	Codec errors usually mean incompatible binaries or payload shape.
Change streams	maybe	no	Change streams are observability surfaces, not durable event streams.