Error codes feedback from mintlify analytics + survey

[shreyas-da]

Topology and party visibility

• UNKNOWN_INFORMEES: 1 chat conversation, cited independently by 3 survey respondents. The participant is not connected to any synchronizer where the given informees are known. Causes seen: external party with an empty PartyToParticipant mapping, and topology not yet propagated after onboarding.
• UNKNOWN_SUBMITTERS: 6 turns in one conversation. Fresh issuer parties failing repeatedly on create. gRPC code 11, same shape as the above but submitter-side.
• TOPOLOGY_STORE_NOT_FOUND: Topology store 'global-domain::1220be58...::35-3' is not known.
• INITIAL_ONBOARDING_ERROR: Unable to register onboarding topology transactions, traced by the user to a rollback on 28 Jun.

Authorization and user rights

• PERMISSION_DENIED: 8 separate conversations. Claims do not authorize to read data for party 'hsbcgps::1220eb9e...'.
• 403 CanActAs: survey [25]: "the error didn't show whether the problem was in the JWT scope, party allocation, or user rights mapping, so I wasted days trial-and-erroring."
• TOO_MANY_USER_RIGHTS: 3 conversations. grant user rights failed, as user would have too many rights. Broke wallet onboarding at scale. Introduced in 0.6.8 with no release note.

Package, DAR and version resolution

• JSON_API_PACKAGE_SELECTION_FAILED: 4 conversations, plus 2 site searches at 0% CTR. No synchronizer satisfies the vetting requirements. Discarded synchronizers: List((glo....
• PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER: 4 conversations. Cannot autodetect synchronizer: no synchronizers currently connected.
• UNRESOLVED_PACKAGE_NAME: Update failed due to a failed package name resolution: utility-registry-app.
• PACKAGE_NAMES_NOT_FOUND: returned when a signatory create came from a third-party (Loop) wallet.
• NOT_VALID_UPGRADE_PACKAGE: Upgrade checks indicate that 2bc6b545d944....
• PACKAGE_OR_DAR_REMOVAL_ERROR: arrived nested as FAILED_PRECONDITION/PACKAGE_OR_DAR_REMOVAL_ERROR.
• INVALID_DAR: Dar file is corrupt on upload, 2 turns.
• Package ID drift (no error code): survey [7]: a rebuild on a different SDK patch produced different package IDs, existing contracts became invisible to generated types, and failures surfaced only as generic template lookup errors.

Synchronizer connectivity

• SYNC_SERVICE_UNKNOWN_SYNCHRONIZER: 4 conversations, 3 searches at 0% CTR. The synchronizer with alias global-domain is unknown and The synchronizer with alias global is unknown.
• SYNC_SERVICE_SYNCHRONIZER_DISCONNECTED: Synchronizer 'global' fatally disconnected because of handler returned....
• SEQUENCER_REQUEST_FAILED: 1 conversation, 2 searches, all 0% CTR.
• NOT_SEQUENCED_TIMEOUT: asked verbatim as "IS THIS FROM MY NODE OR D FULL DEVNET HAVING ISSUE".

Contract state and contention

• CONTRACT_NOT_FOUND: 11 turns across 7 conversations. One user verified the contract ID matched a genuinely active AmuletRules contract and the real cause was missing explicit disclosure. Survey [32] listed four possible meanings they could not distinguish between.
• CONTRACT_NOT_ACTIVE: 8 turns across 5 conversations, usually paired with the above in retry and cache-invalidation logic.
• LOCAL_VERDICT_INACTIVE_CONTRACTS: stale contract references under network instability. The user reported it retrying for hours.
• INACTIVE_CONTRACTS: survey [24]: input holdings archived between prepare and execute (concurrent spend).
• LOCAL_VERDICT_LOCKED_CONTRACTS: 1 search, converts at 100%.
• WRONGLY_TYPED_CONTRACT: on a transfer-offers POST, HTTP 400.
• CONTRACT_DOES_NOT_IMPLEMENT_INTERFACE: Expected Splice.Api.Token.AllocationV1:Allocation@3eacd4c6 but contract has type....

External signing

• FAILED_TO_EXECUTE_TRANSACTION: 2 conversations. Received 0 valid signatures from distinct keys (1 invalid) and Could not find party signing key. One user noted it worked in April 2026 with 32 bytes but now returns this unless multihash-encoded (0x1220 prefix plus 32 bytes).
• INVALID_ARGUMENT on /v2/parties/external/allocate: Topology transaction is missing authorizations by namespaces=Set(1220c0e933...) and keys=Set(12205c50a9e...). Also seen on TransferOffer_Accept: Invalid template:7a75ef6e....

Config and startup

• GENERIC_CONFIG_ERROR: Cannot convert configuration to a config of class com.digitalasset.canton.config.CantonConfig. Failures....
• CONFIG_SUBSTITUTION_ERROR: Received an exception (full stack trace has been logged at DEBUG level).
• FAILED_PRECONDITION / User ledger-api-user has no primary party: 6 turns across 4 conversations. This is the error behind survey [4]'s multi-day validator crash loop. Also 2 searches at 50% CTR.
• CantonHaCoordinatorStepDown: a Prometheus alert rather than an error code, pasted into the Assistant with no useful answer returned.

API and protocol

• LEDGER_API_INTERNAL_ERROR: 4 conversations, two distinct causes. Cannot decode frame: Text(jwt.token.eyJhbG...) when passing a token as the first WebSocket message, and Expected ujson.Str (data: {"status":"Open"}).
• COMMAND_PREPROCESSING_FAILED: 2 conversations. Missing non-optional fields: Set(context, meta) and unknown module ffab4835...:TermsOfServ....
• INVALID_FIELD: expected a package name, hit when using the #splice-util-batched-markers:... alias form.
• JSON_API_MAXIMUM_LIST_ELEMENTS_NUMBER_REACHED: 1 search, converts at 100%.
• MAX_REQUEST_SIZE_EXCEEDED: searched as "request entity too large", converts.
• PARTICIPANT_BACKPRESSURE: searched bare, 1 conversation.
• ACS_COMMITMENT_MISMATCH: searched as "commitment-mismatch", converts at 100%.
• INFORMEES_NOT_ACTIVE: 2 searches. Distinct from UNKNOWN_INFORMEES.

Tooling

• dpm: project uses both opt-in components and sdk bundle, but dpm does not allow usage of both simultaneously. Searched twice. The short phrasing converts at 100%. The full string prefixed with Failed to obtain version information from dpm converts at 0%.