# Error codes¶

Almost all errors and warnings that can be generated by a Canton based system are annotated with error codes of the form SOMETHING_NOT_SO_GOOD_HAPPENED(x,c). These error codes allow a developer, user or operator to identify the exact error occurring such that an error can be automatically handled or looked up in the documentation.

In the above example, the upper case string with underscores denotes the unique error id. The parentheses include key additional information. The id together with the extra information is referred to as error-code. The x represents the ErrorCategory used to classify the error, and the c represents the first 8 characters of the correlation-id associated to this request, or 0 if no correlation-id is given.

The purpose of the correlation-id is to allow a user to clearly identify the request, such that the operator can lookup any log information associated with this error.

The majority of the errors are a result of some request processing. Such errors are logged, with a log level usually depending on the category, and returned to the user as a failed gRPC request (using the standard StatusRuntimeException). In some cases, errors occur due to background processes (i.e. network connection issues / transaction confirmation processing). Such errors are only logged.

Generally, we use the following log-levels on the server:

• INFO to log user errors, where the error leads to a failure of the request but the system remains healthy.

• WARN to log degradations of the system or point out rather unusual behaviour.

• ERROR to log internal errors within the system, where the system does not behave properly and immediate attention is required.

On the client side, failures are considered to be errors and logged as such.

## Error Categories¶

The error categories allow to group errors such that application logic can be built in a sensible way to automatically deal with errors and decide whether to retry a request or escalate to the operator.

The error categories are currently documented as part of our scaladoc reference page.

Every error on the API is constructed in a way that allows automated and manual error handling. First, the error category will map to exactly one gRPC status code. Second, every error description (of the corresponding StatusRuntimeException.Status) will start with the error information (SOMETHING_NOT_SO_GOOD_HAPPENED(CN,x)), separated from a human readable description using a colon (“:”). The rest of the description is targeting humans and should never be parsed by applications, as the description might change in future releases to improve clarity.

In addition to the status code and the description, the gRPC rich error model is used to convey additional, machine readable information to the application.

Therefore, to support automatic error processing, an application may:

• parse the error information from the beginning of the description to obtain the error-id, the error category and the component.

• use the gRPC-code to get the set of possible error categories

• if present, use the ResourceInfo included as Status.details. Any request that fails due to some well-defined resource issues (contract, contract-key, package, party, template, domain) will contain these, calling out on what resource the failure is based on.

• use the RetryInfo to determine the recommended retry interval (or make this decision based on the category / gRPC code).

• use the RequestInfo.id as the correlation-id, included as Status.details

• use the ErrorInfo.reason as error-id and ErrorInfo.metadata("category") as error category, included as Status.details.

All this information is included in errors that are generated by components under our control and included as Status.details. Many errors will include more information, but there is no guarantee given that additional information will be preserved across versions.

Generally, automated error handling can be done on any level (e.g. load balancer using gRPC status codes, application using ErrorCategory or human reacting to error-ids). In most cases, it is advisable to deal with errors on a per category basis and deal with error-ids in very specific situations which are application dependent. As an example, a command failure with the message “CONTRACT_NOT_FOUND” may be an application failure in case the given application is the only actor on the contracts, whereas a “CONTRACT_NOT_FOUND” message is to be expected in a case where multiple independent actors operate on the ledger state.

## List of error codes¶

### 1.1. Errors¶

#### ACS_COMMITMENT_INTERNAL_ERROR¶

• Explanation: This error indicates that there was an internal error within the ACS commitment processing.

• Resolution: Inspect error message for details.

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side.

### 1.1.1. MismatchError¶

#### ACS_COMMITMENT_MISMATCH¶

• Explanation: This error indicates that a remote participant has sent a commitment over an ACS for a period which does not match the local commitment. This error occurs if a remote participant has manually changed contracts using repair, or due to byzantine behavior, or due to malfunction of the system. The consequence is that the ledger is forked, and some commands that should pass will not.

• Resolution: Please contact the other participant in order to check the cause of the mismatch. Either repair the store of this participant or of the counterparty.

• Conveyance: This error is logged with log-level WARN on the server side.

#### ACS_MISMATCH_NO_SHARED_CONTRACTS¶

• Explanation: This error indicates that a remote participant has sent a commitment over an ACS for a period, while this participant does not think that there is a shared contract state. This error occurs if a remote participant has manually changed contracts using repair, or due to byzantine behavior, or due to malfunction of the system. The consequence is that the ledger is forked, and some commands that should pass will not.

• Resolution: Please contact the other participant in order to check the cause of the mismatch. Either repair the store of this participant or of the counterparty.

• Conveyance: This error is logged with log-level WARN on the server side.

### 1.2. TopologyManagerError¶

#### CERTIFICATE_GENERATION_ERROR¶

• Explanation: This error indicates that the desired certificate could not be created.

• Resolution: Inspect the underlying error for details.

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

#### DUPLICATE_TOPOLOGY_TRANSACTION¶

• Explanation: This error indicates that a transaction has already been added previously.

• Resolution: Nothing to do as the transaction is already registered. Note however that a revocation is ” + final. If you want to re-enable a statement, you need to re-issue an new transaction.

• Category: InvalidGivenCurrentSystemStateResourceExists

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message

#### INVALID_TOPOLOGY_TX_SIGNATURE_ERROR¶

• Explanation: This error indicates that the uploaded signed transaction contained an invalid signature.

• Resolution: Ensure that the transaction is valid and uses a crypto version understood by this participant.

• Category: InvalidIndependentOfSystemState

• Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

#### NO_APPROPRIATE_SIGNING_KEY_IN_STORE¶

• Explanation: This error results if the topology manager did not find a secret key in its store to authorize a certain topology transaction.

• Resolution: Inspect your topology transaction and your secret key store and check that you have the appropriate certificates and keys to issue the desired topology transaction. If the list of candidates is empty, then you are missing the certificates.

• Category: InvalidGivenCurrentSystemStateResourceMissing

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message

#### NO_CORRESPONDING_ACTIVE_TX_TO_REVOKE¶

• Explanation: This error indicates that the attempt to add a removal transaction was rejected, as the mapping / element affecting the removal did not exist.

• Resolution: Inspect the topology state and ensure the mapping and the element id of the active transaction you are trying to revoke matches your revocation arguments.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

#### PUBLIC_KEY_NOT_IN_STORE¶

• Explanation: This error indicates that a command contained a fingerprint referring to a public key not being present in the public key store.

• Resolution: Upload the public key to the public key store using $node.keys.public.load(.) before retrying. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: PUBLIC_KEY_NOT_IN_STORE #### REMOVING_LAST_KEY_MUST_BE_FORCED¶ • Explanation: This error indicates that the attempted key removal would remove the last valid key of the given entity, making the node unusuable. • Resolution: Add the force = true flag to your command if you are really sure what you are doing. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: REMOVING_LAST_KEY_MUST_BE_FORCED #### SECRET_KEY_NOT_IN_STORE¶ • Explanation: This error indicates that the secret key with the respective fingerprint can not be found. • Resolution: Ensure you only use fingerprints of secret keys stored in your secret key store. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: SECRET_KEY_NOT_IN_STORE #### TOPOLOGY_MANAGER_INTERNAL_ERROR¶ • Explanation: This error indicates that there was an internal error within the topology manager. • Resolution: Inspect error message for details. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: TOPOLOGY_MANAGER_INTERNAL_ERROR #### TOPOLOGY_MAPPING_ALREADY_EXISTS¶ • Explanation: This error indicates that a transaction would create a state that already exists and has been authorized with the same key. • Resolution: Your intended change is already in effect. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: TOPOLOGY_MAPPING_ALREADY_EXISTS #### UNAUTHORIZED_TOPOLOGY_TRANSACTION¶ • Explanation: This error indicates that the attempt to add a transaction was rejected, as the signing key is not authorized within the current state. • Resolution: Inspect the topology state and ensure that valid namespace or identifier delegations of the signing key exist or upload them before adding this transaction. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: UNAUTHORIZED_TOPOLOGY_TRANSACTION ### 1.2.1. DomainTopologyManagerError¶ #### ALIEN_DOMAIN_ENTITIES¶ • Explanation: This error is returned if a transaction attempts to add keys for alien domain manager or sequencer entities to this domain topology manager. • Resolution: Use a participant topology manager if you want to manage foreign domain keys • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: ALIEN_DOMAIN_ENTITIES #### FAILED_TO_ADD_MEMBER¶ • Explanation: This error indicates an external issue with the member addition hook. • Resolution: Consult the error details. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: FAILED_TO_ADD_MEMBER #### PARTICIPANT_NOT_INITIALIZED¶ • Explanation: This error is returned if a domain topology manager attempts to activate a participant without having previously registered the necessary keys. • Resolution: Register the necessary keys and try again. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: PARTICIPANT_NOT_INITIALIZED #### WRONG_DOMAIN¶ • Explanation: This error is returned if a transaction restricted to a domain should be added to another domain. • Resolution: Recreate the content of the transaction with a correct domain identifier. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: WRONG_DOMAIN ### 1.2.2. ParticipantTopologyManagerError¶ #### CANNOT_VET_DUE_TO_MISSING_PACKAGES¶ • Explanation: This error indicates that a package vetting command failed due to packages not existing locally. This can be due to either the packages not being present or their dependencies being missing. When vetting a package, the package must exist on the participant, as otherwise the participant will not be able to process a transaction relying on a particular package. • Resolution: Ensure that the package exists locally before issuing such a transaction. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: CANNOT_VET_DUE_TO_MISSING_PACKAGES #### DANGEROUS_KEY_USE_COMMAND_REQUIRES_FORCE¶ • Explanation: This error indicates that a dangerous owner to key mapping authorization was rejected. This is the case if a command is run that could break a participant. If the command was run to assign a key for the given participant, then the command was rejected because the key is not in the participants private store. If the command is run on a participant to issue transactions for another participant, then such commands must be run with force, as they are very dangerous and could easily break the participant. As an example, if we assign an encryption key to a participant that the participant does not have, then the participant will be unable to process an incoming transaction. Therefore we must be very careful to not create such situations. • Resolution: Set force=true if you really know what you are doing. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DANGEROUS_KEY_USE_COMMAND_REQUIRES_FORCE #### DANGEROUS_VETTING_COMMANDS_REQUIRE_FORCE¶ • Explanation: This error indicates that a dangerous package vetting command was rejected. This is the case if a vetting command, if not run correctly, could potentially lead to a ledger fork. The vetting authorization checks the participant for the presence of the given set of packages (including their dependencies) and allows only to vet for the given participant id. In rare cases where a more centralised topology manager is used, this behaviour can be overridden with force. However, if a package is vetted but not present on the participant, the participant will refuse to process any transaction of the given domain until the problematic package has been uploaded. • Resolution: Set force=true if you really know what you are doing. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DANGEROUS_VETTING_COMMANDS_REQUIRE_FORCE #### DEPENDENCIES_NOT_VETTED¶ • Explanation: This error indicates a vetting request failed due to dependencies not being vetted. On every vetting request, the set supplied packages is analysed for dependencies. The system requires that not only the main packages are vetted explicitly but also all dependencies. This is necessary as not all participants are required to have the same packages installed and therefore not every participant can resolve the dependencies implicitly. • Resolution: Vet the dependencies first and then repeat your attempt. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DEPENDENCIES_NOT_VETTED #### UNINITIALIZED_PARTICIPANT¶ • Explanation: This error indicates that a request involving topology management was attempted on a participant that is not yet initialised. During initialisation, only namespace and identifier delegations can be managed. • Resolution: Initialise the participant and retry. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: UNINITIALIZED_PARTICIPANT ### 1.2.3. Domain¶ ### 1.2.3.1. GrpcSequencerAuthenticationService¶ #### CLIENT_AUTHENTICATION_FAULTY¶ • Explanation: This error indicates that a client failed to authenticate with the sequencer due to a reason possibly pointing out to faulty or malicious behaviour. The message is logged on the server in order to support an operator to provide explanations to clients struggling to connect. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. • Scaladocs: CLIENT_AUTHENTICATION_FAULTY #### CLIENT_AUTHENTICATION_REJECTED¶ • Explanation: This error indicates that a client failed to authenticate with the sequencer. The message is logged on the server in order to support an operator to provide explanations to clients struggling to connect. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. • Scaladocs: CLIENT_AUTHENTICATION_REJECTED ### 1.3. LedgerApiErrors¶ #### CONFIGURATION_ENTRY_REJECTED¶ • Explanation: This rejection is given when a new configuration is rejected. • Resolution: Fetch newest configuration and/or retry. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: CONFIGURATION_ENTRY_REJECTED #### LEDGER_API_INTERNAL_ERROR¶ • Explanation: This error occurs if there was an unexpected error in the Ledger API. • Resolution: Contact support. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: LEDGER_API_INTERNAL_ERROR #### PACKAGE_UPLOAD_REJECTED¶ • Explanation: This rejection is given when a package upload is rejected. • Resolution: Refer to the detailed message of the received error. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: PACKAGE_UPLOAD_REJECTED #### PARTICIPANT_BACKPRESSURE¶ • Explanation: This error occurs when a participant rejects a command due to excessive load. Load can be caused by the following factors: 1. when commands are submitted to the participant through its Ledger API, 2. when the participant receives requests from other participants through a connected domain. • Resolution: Wait a bit and retry, preferably with some backoff factor. If possible, ask other participants to send fewer requests; the domain operator can enforce this by imposing a rate limit. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: PARTICIPANT_BACKPRESSURE #### REQUEST_TIME_OUT¶ • Explanation: This rejection is given when a request processing status is not known and a time-out is reached. • Resolution: Retry for transient problems. If non-transient contact the operator as the time-out limit might be too short. • Category: DeadlineExceededRequestStateUnknown • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status DEADLINE_EXCEEDED including a detailed error message • Scaladocs: REQUEST_TIME_OUT #### SERVICE_NOT_RUNNING¶ • Explanation: This rejection is given when the requested service has already been closed. • Resolution: Retry re-submitting the request. If the error persists, contact the participant operator. • Category: TransientServerFailure • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message • Scaladocs: SERVICE_NOT_RUNNING #### USER_ALREADY_EXISTS¶ • Explanation: There already exists a user with the same user-id. • Resolution: Check that you are connecting to the right participant node and the user-id is spelled correctly, or use the user that already exists. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: USER_ALREADY_EXISTS #### USER_NOT_FOUND¶ • Explanation: The user referred to by the request was not found. • Resolution: Check that you are connecting to the right participant node and the user-id is spelled correctly, if yes, create the user. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: USER_NOT_FOUND ### 1.3.1. CommandExecution¶ #### FAILED_TO_DETERMINE_LEDGER_TIME¶ • Explanation: This error occurs if the participant fails to determine the max ledger time of the used contracts. Most likely, this means that one of the contracts is not active anymore which can happen under contention. It can also happen with contract keys. • Resolution: Retry the transaction submission. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: FAILED_TO_DETERMINE_LEDGER_TIME ### 1.3.1.1. Package¶ #### ALLOWED_LANGUAGE_VERSIONS¶ • Explanation: This error indicates that the uploaded DAR is based on an unsupported language version. • Resolution: Use a DAR compiled with a language version that this participant supports. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: ALLOWED_LANGUAGE_VERSIONS #### PACKAGE_VALIDATION_FAILED¶ • Explanation: This error occurs if a package referred to by a command fails validation. This should not happen as packages are validated when being uploaded. • Resolution: Contact support. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: PACKAGE_VALIDATION_FAILED ### 1.3.1.2. Preprocessing¶ #### COMMAND_PREPROCESSING_FAILED¶ • Explanation: This error occurs if a command fails during interpreter pre-processing. • Resolution: Inspect error details and correct your application. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: COMMAND_PREPROCESSING_FAILED ### 1.3.1.3. Interpreter¶ #### CONTRACT_NOT_ACTIVE¶ • Explanation: This error occurs if an exercise or fetch happens on a transaction-locally consumed contract. • Resolution: This error indicates an application error. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: CONTRACT_NOT_ACTIVE #### DAML_AUTHORIZATION_ERROR¶ • Explanation: This error occurs if a Daml transaction fails due to an authorization error. An authorization means that the Daml transaction computed a different set of required submitters than you have provided during the submission as actAs parties. • Resolution: This error type occurs if there is an application error. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: DAML_AUTHORIZATION_ERROR #### DAML_INTERPRETATION_ERROR¶ • Explanation: This error occurs if a Daml transaction fails during interpretation. • Resolution: This error type occurs if there is an application error. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DAML_INTERPRETATION_ERROR #### DAML_INTERPRETER_INVALID_ARGUMENT¶ • Explanation: This error occurs if a Daml transaction fails during interpretation due to an invalid argument. • Resolution: This error type occurs if there is an application error. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: DAML_INTERPRETER_INVALID_ARGUMENT ### 1.3.1.3.1. LookupErrors¶ #### CONTRACT_KEY_NOT_FOUND¶ • Explanation: This error occurs if the Daml engine interpreter cannot resolve a contract key to an active contract. This can be caused by either the contract key not being known to the participant, or not being known to the submitting parties or the contract representing an already archived key. • Resolution: This error type occurs if there is contention on a contract. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: CONTRACT_KEY_NOT_FOUND ### 1.3.2. ConsistencyErrors¶ #### CONTRACT_NOT_FOUND¶ • Explanation: This error occurs if the Daml engine can not find a referenced contract. This can be caused by either the contract not being known to the participant, or not being known to the submitting parties or already being archived. • Resolution: This error type occurs if there is contention on a contract. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: CONTRACT_NOT_FOUND #### DUPLICATE_COMMAND¶ • Explanation: A command with the given command id has already been successfully processed. • Resolution: The correct resolution depends on the use case. If the error received pertains to a submission retried due to a timeout, do nothing, as the previous command has already been accepted. If the intent is to submit a new command, re-submit using a distinct command id. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: DUPLICATE_COMMAND #### DUPLICATE_CONTRACT_KEY¶ • Explanation: This error signals that within the transaction we got to a point where two contracts with the same key were active. • Resolution: This error indicates an application error. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: DUPLICATE_CONTRACT_KEY #### INCONSISTENT¶ • Explanation: At least one input has been altered by a concurrent transaction submission. • Resolution: The correct resolution depends on the business flow, for example it may be possible to proceed without an archived contract as an input, or the transaction submission may be retried to load the up-to-date value of a contract key. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INCONSISTENT #### INCONSISTENT_CONTRACTS¶ • Explanation: An input contract has been archived by a concurrent transaction submission. • Resolution: The correct resolution depends on the business flow, for example it may be possible to proceed without the archived contract as an input, or a different contract could be used. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INCONSISTENT_CONTRACTS #### INCONSISTENT_CONTRACT_KEY¶ • Explanation: An input contract key was re-assigned to a different contract by a concurrent transaction submission. • Resolution: Retry the transaction submission. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INCONSISTENT_CONTRACT_KEY #### INVALID_LEDGER_TIME¶ • Explanation: The ledger time of the submission violated some constraint on the ledger time. • Resolution: Retry the transaction submission. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INVALID_LEDGER_TIME #### SUBMISSION_ALREADY_IN_FLIGHT¶ • Explanation: Another command submission with the same change ID (application ID, command ID, actAs) is already being processed. • Resolution: Listen to the command completion stream until a completion for the in-flight command submission is published. Alternatively, resubmit the command. If the in-flight submission has finished successfully by then, this will return more detailed information about the earlier one. If the in-flight submission has failed by then, the resubmission will attempt to record the new transaction on the ledger. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: SUBMISSION_ALREADY_IN_FLIGHT ### 1.3.3. PackageServiceError¶ #### DAR_NOT_SELF_CONSISTENT¶ • Explanation: This error indicates that the uploaded Dar is broken because it is missing internal dependencies. • Resolution: Contact the supplier of the Dar. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: DAR_NOT_SELF_CONSISTENT #### DAR_VALIDATION_ERROR¶ • Explanation: This error indicates that the validation of the uploaded dar failed. • Resolution: Inspect the error message and contact support. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: DAR_VALIDATION_ERROR #### PACKAGE_SERVICE_INTERNAL_ERROR¶ • Explanation: This error indicates an internal issue within the package service. • Resolution: Inspect the error message and contact support. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: PACKAGE_SERVICE_INTERNAL_ERROR ### 1.3.3.1. Reading¶ #### DAR_PARSE_ERROR¶ • Explanation: This error indicates that the content of the Dar file could not be parsed successfully. • Resolution: Inspect the error message and contact support. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: DAR_PARSE_ERROR #### INVALID_DAR¶ • Explanation: This error indicates that the supplied dar file was invalid. • Resolution: Inspect the error message for details and contact support. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_DAR #### INVALID_DAR_FILE_NAME¶ • Explanation: This error indicates that the supplied dar file name did not meet the requirements to be stored in the persistence store. • Resolution: Inspect error message for details and change the file name accordingly • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_DAR_FILE_NAME #### INVALID_LEGACY_DAR¶ • Explanation: This error indicates that the supplied zipped dar is an unsupported legacy Dar. • Resolution: Please use a more recent dar version. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_LEGACY_DAR #### INVALID_ZIP_ENTRY¶ • Explanation: This error indicates that the supplied zipped dar file was invalid. • Resolution: Inspect the error message for details and contact support. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_ZIP_ENTRY #### ZIP_BOMB¶ • Explanation: This error indicates that the supplied zipped dar is regarded as zip-bomb. • Resolution: Inspect the dar and contact support. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: ZIP_BOMB ### 1.3.4. WriteServiceRejections¶ #### DISPUTED¶ • Explanation: An invalid transaction submission was not detected by the participant. • Resolution: Contact support. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: DISPUTED #### OUT_OF_QUOTA¶ • Explanation: The Participant node did not have sufficient resource quota to submit the transaction. • Resolution: Inspect the error message and retry after after correcting the underlying issue. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: OUT_OF_QUOTA #### PARTY_NOT_KNOWN_ON_LEDGER¶ • Explanation: One or more informee parties have not been allocated. • Resolution: Check that all the informee party identifiers are correct, allocate all the informee parties, request their allocation or wait for them to be allocated before retrying the transaction submission. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: PARTY_NOT_KNOWN_ON_LEDGER #### SUBMITTER_CANNOT_ACT_VIA_PARTICIPANT¶ • Explanation: A submitting party is not authorized to act through the participant. • Resolution: Contact the participant operator or re-submit with an authorized party. • Category: InsufficientPermission • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status PERMISSION_DENIED without any details due to security reasons • Scaladocs: SUBMITTER_CANNOT_ACT_VIA_PARTICIPANT #### SUBMITTING_PARTY_NOT_KNOWN_ON_LEDGER¶ • Explanation: The submitting party has not been allocated. • Resolution: Check that the party identifier is correct, allocate the submitting party, request its allocation or wait for it to be allocated before retrying the transaction submission. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: SUBMITTING_PARTY_NOT_KNOWN_ON_LEDGER ### 1.3.5. AuthorizationChecks¶ #### INTERNAL_AUTHORIZATION_ERROR¶ • Explanation: An internal system authorization error occurred. • Resolution: Contact the participant operator. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: INTERNAL_AUTHORIZATION_ERROR #### PERMISSION_DENIED¶ • Explanation: This rejection is given if the supplied authorization token is not sufficient for the intended command. The exact reason is logged on the participant, but not given to the user for security reasons. • Resolution: Inspect your command and your token or ask your participant operator for an explanation why this command failed. • Category: InsufficientPermission • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status PERMISSION_DENIED without any details due to security reasons • Scaladocs: PERMISSION_DENIED #### UNAUTHENTICATED¶ • Explanation: This rejection is given if the submitted command does not contain a JWT token on a participant enforcing JWT authentication. • Resolution: Ask your participant operator to provide you with an appropriate JWT token. • Category: AuthInterceptorInvalidAuthenticationCredentials • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNAUTHENTICATED without any details due to security reasons • Scaladocs: UNAUTHENTICATED ### 1.3.6. RequestValidation¶ #### INVALID_ARGUMENT¶ • Explanation: This error is emitted when a submitted ledger API command contains an invalid argument. • Resolution: Inspect the reason given and correct your application. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_ARGUMENT #### INVALID_DEDUPLICATION_PERIOD¶ • Explanation: This error is emitted when a submitted ledger API command specifies an invalid deduplication period. • Resolution: Inspect the error message, adjust the value of the deduplication period or ask the participant operator to increase the maximum deduplication period. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INVALID_DEDUPLICATION_PERIOD #### INVALID_FIELD¶ • Explanation: This error is emitted when a submitted ledger API command contains a field value that cannot be understood. • Resolution: Inspect the reason given and correct your application. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_FIELD #### LEDGER_ID_MISMATCH¶ • Explanation: Every ledger API command contains a ledger-id which is verified against the running ledger. This error indicates that the provided ledger-id does not match the expected one. • Resolution: Ensure that your application is correctly configured to use the correct ledger. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: LEDGER_ID_MISMATCH #### MISSING_FIELD¶ • Explanation: This error is emitted when a mandatory field is not set in a submitted ledger API command. • Resolution: Inspect the reason given and correct your application. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: MISSING_FIELD #### NON_HEXADECIMAL_OFFSET¶ • Explanation: The supplied offset could not be converted to a binary offset. • Resolution: Ensure the offset is specified as a hexadecimal string. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: NON_HEXADECIMAL_OFFSET #### OFFSET_AFTER_LEDGER_END¶ • Explanation: This rejection is given when a read request uses an offset beyond the current ledger end. • Resolution: Use an offset that is before the ledger end. • Category: InvalidGivenCurrentSystemStateSeekAfterEnd • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status OUT_OF_RANGE including a detailed error message • Scaladocs: OFFSET_AFTER_LEDGER_END #### OFFSET_OUT_OF_RANGE¶ • Explanation: This rejection is given when a read request uses an offset invalid in the requests’ context. • Resolution: Inspect the error message and use a valid offset. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: OFFSET_OUT_OF_RANGE #### PARTICIPANT_PRUNED_DATA_ACCESSED¶ • Explanation: This rejection is given when a read request tries to access pruned data. • Resolution: Use an offset that is after the pruning offset. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: PARTICIPANT_PRUNED_DATA_ACCESSED ### 1.3.6.1. NotFound¶ #### LEDGER_CONFIGURATION_NOT_FOUND¶ • Explanation: The ledger configuration could not be retrieved. This could happen due to incomplete initialization of the participant or due to an internal system error. • Resolution: Contact the participant operator. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: LEDGER_CONFIGURATION_NOT_FOUND #### PACKAGE_NOT_FOUND¶ • Explanation: This rejection is given when a read request tries to access a package which does not exist on the ledger. • Resolution: Use a package id pertaining to a package existing on the ledger. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: PACKAGE_NOT_FOUND #### TRANSACTION_NOT_FOUND¶ • Explanation: The transaction does not exist or the requesting set of parties are not authorized to fetch it. • Resolution: Check the transaction id and verify that the requested transaction is visible to the requesting parties. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: TRANSACTION_NOT_FOUND ### 1.4. TransactionErrorGroup¶ ### 1.4.1. TransactionRoutingError¶ #### AUTOMATIC_TRANSFER_FOR_TRANSACTION_FAILED¶ • Explanation: This error indicates that the automated transfer could not succeed, as the current topology does not allow the transfer to complete, mostly due to lack of confirmation permissions of the involved parties. • Resolution: Inspect the message and your topology and ensure appropriate permissions exist. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message #### ROUTING_INTERNAL_ERROR¶ • Explanation: This error indicates an internal error in the Canton domain router. • Resolution: Please contact support. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: ROUTING_INTERNAL_ERROR ### 1.4.1.1. TopologyErrors¶ #### INFORMEES_NOT_ACTIVE¶ • Explanation: This error indicates that the informees are known, but there is no connected domain on which all the informees are hosted. • Resolution: Ensure that there is such a domain, as Canton requires a domain where all informees are present. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INFORMEES_NOT_ACTIVE #### NOT_CONNECTED_TO_ALL_CONTRACT_DOMAINS¶ • Explanation: This error indicates that the transaction is referring to contracts on domains to which this participant is currently not connected. • Resolution: Check the status of your domain connections. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: NOT_CONNECTED_TO_ALL_CONTRACT_DOMAINS #### NO_COMMON_DOMAIN¶ • Explanation: This error indicates that there is no common domain to which all submitters can submit and all informees are connected. • Resolution: Check that your participant node is connected to all domains you expect and check that the parties are hosted on these domains as you expect them to be. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: NO_COMMON_DOMAIN #### NO_DOMAIN_ON_WHICH_ALL_SUBMITTERS_CAN_SUBMIT¶ • Explanation: This error indicates that a transaction has been sent where the system can not find any active ” + “domain on which this participant can submit in the name of the given set of submitters. • Resolution: Ensure that you are connected to a domain where this participant has submission rights. Check that you are actually connected to the domains you expect to be connected and check that your participant node has the submission permission for each submitting party. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message #### SUBMITTER_ALWAYS_STAKEHOLDER¶ • Explanation: This error indicates that the transaction requires contract transfers for which the submitter must be a stakeholder. • Resolution: Check that your participant node is connected to all domains you expect and check that the parties are hosted on these domains as you expect them to be. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: SUBMITTER_ALWAYS_STAKEHOLDER #### UNKNOWN_CONTRACT_DOMAINS¶ • Explanation: This error indicates that the transaction is referring to contracts whose domain is not currently known. • Resolution: Ensure all transfer operations on contracts used by the transaction have completed. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: UNKNOWN_CONTRACT_DOMAINS #### UNKNOWN_INFORMEES¶ • Explanation: This error indicates that the transaction is referring to some informees that are not known on any connected domain. • Resolution: Check the list of submitted informees and check if your participant is connected to the domains you are expecting it to be. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: UNKNOWN_INFORMEES ### 1.4.1.2. MalformedInputErrors¶ #### INVALID_DOMAIN_ALIAS¶ • Explanation: The WorkflowID defined in the transaction metadata is not a valid domain alias. • Resolution: Check that the workflow ID (if specified) corresponds to a valid domain alias. A typical rejection reason is a too-long domain alias. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: INVALID_DOMAIN_ALIAS #### INVALID_SUBMITTER¶ • Explanation: The party defined as a submitter can not be parsed into a valid Canton party. • Resolution: Check that you only use correctly setup party names in your application. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: INVALID_SUBMITTER ### 1.4.1.3. ConfigurationErrors¶ #### MULTI_DOMAIN_SUPPORT_NOT_ENABLED¶ • Explanation: This error indicates that a transaction has been submitted that requires multi-domain support. Multi-domain support is a preview feature that needs to be enabled explicitly by configuration. • Resolution: Set canton.features.enable-preview-commands = yes • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: MULTI_DOMAIN_SUPPORT_NOT_ENABLED #### SUBMISSION_DOMAIN_NOT_READY¶ • Explanation: This error indicates that the transaction should be submitted to a domain which is not connected or not configured. • Resolution: Ensure that the domain is correctly connected. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: SUBMISSION_DOMAIN_NOT_READY ### 1.4.2. SubmissionErrors¶ #### CHOSEN_MEDIATOR_IS_INACTIVE¶ • Explanation: The mediator chosen for the transaction got deactivated before the request was sequenced. • Resolution: Resubmit. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: CHOSEN_MEDIATOR_IS_INACTIVE #### DOMAIN_BACKPRESSURE¶ • Explanation: This error occurs when the sequencer refuses to accept a command due to backpressure. • Resolution: Wait a bit and retry, preferably with some backoff factor. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: DOMAIN_BACKPRESSURE #### DOMAIN_WITHOUT_MEDIATOR¶ • Explanation: The participant routed the transaction to a domain without an active mediator. • Resolution: Add a mediator to the domain. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: DOMAIN_WITHOUT_MEDIATOR #### MALFORMED_REQUEST¶ • Explanation: This error has not yet been properly categorised into sub-error codes. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: MALFORMED_REQUEST #### NOT_SEQUENCED_TIMEOUT¶ • Explanation: This error occurs when the transaction was not sequenced within the pre-defined max-sequencing time and has therefore timed out. The max-sequencing time is derived from the transaction’s ledger time via the ledger time model skews. • Resolution: Resubmit if the delay is caused by high load. If the command requires substantial processing on the participant, specify a higher minimum ledger time with the command submission so that a higher max sequencing time is derived. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: NOT_SEQUENCED_TIMEOUT #### PACKAGE_NO_VETTED_BY_RECIPIENTS¶ • Explanation: This error occurs if a transaction was submitted referring to a package that a receiving participant has not vetted. Any transaction view can only refer to packages that have explicitly been approved by the receiving participants. • Resolution: Ensure that the receiving participant uploads and vets the respective package. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: PACKAGE_NO_VETTED_BY_RECIPIENTS #### SEQUENCER_DELIVER_ERROR¶ • Explanation: This error occurs when the domain refused to sequence the given message. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: SEQUENCER_DELIVER_ERROR #### SEQUENCER_REQUEST_FAILED¶ • Explanation: This error occurs when the command cannot be sent to the domain. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: SEQUENCER_REQUEST_FAILED #### SUBMISSION_DURING_SHUTDOWN¶ • Explanation: This error occurs when a command is submitted while the system is performing a shutdown. • Resolution: Assuming that the participant will restart or failover eventually, retry in a couple of seconds. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: SUBMISSION_DURING_SHUTDOWN ### 1.4.3. SyncServiceInjectionError¶ #### COMMAND_INJECTION_FAILURE¶ • Explanation: This errors occurs if an internal error results in an exception. • Resolution: Contact support. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: COMMAND_INJECTION_FAILURE #### NODE_IS_PASSIVE_REPLICA¶ • Explanation: This error results if a command is submitted to the passive replica. • Resolution: Send the command to the active replica. • Category: TransientServerFailure • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message • Scaladocs: NODE_IS_PASSIVE_REPLICA #### NOT_CONNECTED_TO_ANY_DOMAIN¶ • Explanation: This errors results if a command is submitted to a participant that is not connected to any domain. • Resolution: Connect your participant to the domain where the given parties are hosted. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: NOT_CONNECTED_TO_ANY_DOMAIN ### 1.4.4. LocalReject¶ ### 1.4.4.1. MalformedRejects¶ #### LOCAL_VERDICT_BAD_ROOT_HASH_MESSAGES¶ • Explanation: This rejection is made by a participant if a transaction does not contain valid root hash messages. • Resolution: This indicates a race condition due to a in-flight topology change, or malicious or faulty behaviour. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: LOCAL_VERDICT_BAD_ROOT_HASH_MESSAGES #### LOCAL_VERDICT_DETECTED_MULTIPLE_CONFIRMATION_POLICIES¶ • Explanation: This rejection is made by a participant if a transaction uses different confirmation policies per view. • Resolution: This indicates either malicious or faulty behaviour. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons #### LOCAL_VERDICT_EMPTY_REJECTION¶ • Explanation: This rejection is emitted by a participant if it receives an aggregated reject without any reason. • Resolution: This indicates either malicious or faulty mediator. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: LOCAL_VERDICT_EMPTY_REJECTION #### LOCAL_VERDICT_FAILED_MODEL_CONFORMANCE_CHECK¶ • Explanation: This rejection is made by a participant if a transaction fails a model conformance check. • Resolution: This indicates either malicious or faulty behaviour. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons #### LOCAL_VERDICT_MALFORMED_PAYLOAD¶ • Explanation: This rejection is made by a participant if a view of the transaction is malformed. • Resolution: This indicates either malicious or faulty behaviour. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: LOCAL_VERDICT_MALFORMED_PAYLOAD ### 1.4.4.2. ConsistencyRejections¶ #### LOCAL_VERDICT_CREATES_EXISTING_CONTRACTS¶ • Explanation: This error indicates that the transaction would create already existing contracts. • Resolution: This error indicates either faulty or malicious behaviour. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: LOCAL_VERDICT_CREATES_EXISTING_CONTRACTS #### LOCAL_VERDICT_DUPLICATE_KEY¶ • Explanation: If the participant provides unique contract key support, this error will indicate that a transaction would create a unique key which already exists. • Resolution: It depends on your use case and application whether and when retrying makes sense or not. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: LOCAL_VERDICT_DUPLICATE_KEY #### LOCAL_VERDICT_INACTIVE_CONTRACTS¶ • Explanation: The transaction is referring to contracts that have either been previously archived, transferred to another domain, or do not exist. • Resolution: Inspect your contract state and try a different transaction. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: LOCAL_VERDICT_INACTIVE_CONTRACTS #### LOCAL_VERDICT_INCONSISTENT_KEY¶ • Explanation: If the participant provides unique contract key support, this error will indicate that a transaction expected a key to be unallocated, but a contract for the key already exists. • Resolution: It depends on your use case and application whether and when retrying makes sense or not. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: LOCAL_VERDICT_INCONSISTENT_KEY #### LOCAL_VERDICT_LOCKED_CONTRACTS¶ • Explanation: The transaction is referring to locked contracts which are in the process of being created, transferred, or archived by another transaction. If the other transaction fails, this transaction could be successfully retried. • Resolution: Retry the transaction • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: LOCAL_VERDICT_LOCKED_CONTRACTS #### LOCAL_VERDICT_LOCKED_KEYS¶ • Explanation: The transaction is referring to locked keys which are in the process of being modified by another transaction. • Resolution: Retry the transaction • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: LOCAL_VERDICT_LOCKED_KEYS ### 1.4.4.3. TimeRejects¶ #### LOCAL_VERDICT_LEDGER_TIME_OUT_OF_BOUND¶ • Explanation: This error is thrown if the ledger time and the record time differ more than permitted. This can happen in an overloaded system due to high latencies or for transactions with long interpretation times. • Resolution: For long-running transactions, specify a ledger time with the command submission. For short-running transactions, simply retry. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: LOCAL_VERDICT_LEDGER_TIME_OUT_OF_BOUND #### LOCAL_VERDICT_SUBMISSION_TIME_OUT_OF_BOUND¶ • Explanation: This error is thrown if the submission time and the record time differ more than permitted. This can happen in an overloaded system due to high latencies or for transactions with long interpretation times. • Resolution: For long-running transactions, adjust the ledger time bounds used with the command submission. For short-running transactions, simply retry. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message #### LOCAL_VERDICT_TIMEOUT¶ • Explanation: This rejection is sent if the participant locally determined a timeout. • Resolution: Resubmit your transaction. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: LOCAL_VERDICT_TIMEOUT ### 1.4.4.4. TransferInRejects¶ #### TRANSFER_IN_ALREADY_COMPLETED¶ • Explanation: This rejection is emitted by a participant if a transfer-in has already been completed. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: TRANSFER_IN_ALREADY_COMPLETED #### TRANSFER_IN_CONTRACT_ALREADY_ACTIVE¶ • Explanation: This rejection is emitted by a participant if a transfer-in has already been made by another entity. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: TRANSFER_IN_CONTRACT_ALREADY_ACTIVE #### TRANSFER_IN_CONTRACT_ALREADY_ARCHIVED¶ • Explanation: This rejection is emitted by a participant if a transfer would be invoked on an already archived contract. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: TRANSFER_IN_CONTRACT_ALREADY_ARCHIVED #### TRANSFER_IN_CONTRACT_IS_LOCKED¶ • Explanation: This rejection is emitted by a participant if a transfer-in is referring to an already locked contract. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: TRANSFER_IN_CONTRACT_IS_LOCKED ### 1.4.4.5. TransferOutRejects¶ #### TRANSFER_OUT_ACTIVENESS_CHECK_FAILED¶ • Explanation: Activeness check failed for transfer out submission. This rejection occurs if the contract to be transferred has already been transferred or is currently locked (due to a competing transaction) on domain. • Resolution: Depending on your use-case and your expectation, retry the transaction. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: TRANSFER_OUT_ACTIVENESS_CHECK_FAILED ### 1.4.5. CommandDeduplicationError¶ #### MALFORMED_DEDUPLICATION_OFFSET¶ • Explanation: The specified deduplication offset is syntactically malformed. • Resolution: Use a deduplication offset that was produced by this participant node. • Category: InvalidIndependentOfSystemState • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message • Scaladocs: MALFORMED_DEDUPLICATION_OFFSET ### 1.4.6. MediatorReject¶ #### MEDIATOR_SAYS_TX_TIMED_OUT¶ • Explanation: This rejection indicates that the transaction has been rejected by the mediator as it didn’t receive enough confirmations within the confirmation timeout window. • Resolution: Check that all involved participants are available and not overloaded. • Category: ContentionOnSharedResources • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ABORTED including a detailed error message • Scaladocs: MEDIATOR_SAYS_TX_TIMED_OUT ### 1.4.6.1. MaliciousSubmitter¶ #### MEDIATOR_SAYS_DECLARED_MEDIATOR_IS_WRONG¶ • Explanation: This rejection indicates that the submitter sent the request to the wrong mediator • Resolution: Investigate whether the submitter is faulty or malicious. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons • Scaladocs: MEDIATOR_SAYS_DECLARED_MEDIATOR_IS_WRONG #### MEDIATOR_SAYS_NOT_ENOUGH_CONFIRMING_PARTIES¶ • Explanation: This rejection indicates that a submitter has sent a manipulated view. • Resolution: Investigate whether the submitter is faulty or malicious. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons #### MEDIATOR_SAYS_VIEW_THRESHOLD_BELOW_MINIMUM_THRESHOLD¶ • Explanation: This rejection indicates that a submitter has sent a manipulated view. • Resolution: Investigate whether the submitter is faulty or malicious. • Category: MaliciousOrFaultyBehaviour • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status UNKNOWN without any details due to security reasons ### 1.4.6.2. Topology¶ #### MEDIATOR_SAYS_INFORMEES_NOT_HOSTED_ON_ACTIVE_PARTICIPANTS¶ • Explanation: The transaction is referring to informees that are not hosted on any active participant on this domain. • Resolution: This error can happen either if the transaction is racing with a topology state change, or due to malicious or faulty behaviour. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message #### MEDIATOR_SAYS_INVALID_ROOT_HASH_MESSAGES¶ • Explanation: This rejection indicates that a submitter has sent a view with invalid root hash messages. • Resolution: This error can happen either if the transaction is racing with a topology state change, or due to malicious or faulty behaviour. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: MEDIATOR_SAYS_INVALID_ROOT_HASH_MESSAGES ### 1.5. SyncServiceError¶ #### SYNC_SERVICE_ALREADY_ADDED¶ • Explanation: This error results on an attempt to register a new domain under an alias already in use. • Category: InvalidGivenCurrentSystemStateResourceExists • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message • Scaladocs: SYNC_SERVICE_ALREADY_ADDED #### SYNC_SERVICE_DOMAIN_DISABLED_US¶ • Explanation: This error is logged when the synchronization service shuts down because the remote domain has disabled this participant. • Resolution: Contact the domain operator and inquire why you have been booted out. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level WARN on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: SYNC_SERVICE_DOMAIN_DISABLED_US #### SYNC_SERVICE_DOMAIN_DISCONNECTED¶ • Explanation: This error is logged when a sync domain is unexpectedly disconnected from the Canton sync service (after having previously been connected) • Resolution: Please contact support and provide the failure reason. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: SYNC_SERVICE_DOMAIN_DISCONNECTED #### SYNC_SERVICE_INTERNAL_ERROR¶ • Explanation: This error indicates an internal issue. • Resolution: Please contact support and provide the failure reason. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: SYNC_SERVICE_INTERNAL_ERROR #### SYNC_SERVICE_UNKNOWN_DOMAIN¶ • Explanation: This error results if a domain connectivity command is referring to a domain alias that has not been registered. • Category: InvalidGivenCurrentSystemStateResourceMissing • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status NOT_FOUND including a detailed error message • Scaladocs: SYNC_SERVICE_UNKNOWN_DOMAIN ### 1.5.1. DomainRegistryError¶ #### DOMAIN_REGISTRY_INTERNAL_ERROR¶ • Explanation: This error indicates that there has been an internal error noticed by Canton. • Resolution: Contact support and provide the failure reason. • Category: SystemInternalAssumptionViolated • Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons • Scaladocs: DOMAIN_REGISTRY_INTERNAL_ERROR ### 1.5.1.1. ConfigurationErrors¶ #### CANNOT_ISSUE_DOMAIN_TRUST_CERTIFICATE¶ • Explanation: This error indicates that the participant can not issue a domain trust certificate. Such a certificate is necessary to become active on a domain. Therefore, it must be present in the authorized store of the participant topology manager. • Resolution: Manually upload a valid domain trust certificate for the given domain or upload the necessary certificates such that participant can issue such certificates automatically. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: CANNOT_ISSUE_DOMAIN_TRUST_CERTIFICATE #### DOMAIN_PARAMETERS_CHANGED¶ • Explanation: Error indicating that the domain parameters have been changed, while this isn’t supported yet. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DOMAIN_PARAMETERS_CHANGED #### INCOMPATIBLE_UNIQUE_CONTRACT_KEYS_MODE¶ • Explanation: This error indicates that the domain this participant is trying to connect to is a domain where unique contract keys are supported, while this participant is already connected to other domains. Multiple domains and unique contract keys are mutually exclusive features. • Resolution: Use isolated participants for domains that require unique keys. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INCOMPATIBLE_UNIQUE_CONTRACT_KEYS_MODE #### INVALID_DOMAIN_CONNECTION¶ • Explanation: This error indicates there is a validation error with the configured connections for the domain • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: INVALID_DOMAIN_CONNECTION ### 1.5.1.2. HandshakeErrors¶ #### DOMAIN_ALIAS_DUPLICATION¶ • Explanation: This error indicates that the domain alias was previously used to connect to a domain with a different domain id. This is a known situation when an existing participant is trying to connect to a freshly re-initialised domain. • Resolution: Carefully verify the connection settings. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DOMAIN_ALIAS_DUPLICATION #### DOMAIN_CRYPTO_HANDSHAKE_FAILED¶ • Explanation: This error indicates that the domain is using crypto settings which are either not supported or not enabled on this participant. • Resolution: Consult the error message and adjust the supported crypto schemes of this participant. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DOMAIN_CRYPTO_HANDSHAKE_FAILED #### DOMAIN_HANDSHAKE_FAILED¶ • Explanation: This error indicates that the participant to domain handshake has failed. • Resolution: Inspect the provided reason for more details and contact support. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DOMAIN_HANDSHAKE_FAILED #### DOMAIN_ID_MISMATCH¶ • Explanation: This error indicates that the domain-id does not match the one that the participant expects. If this error happens on a first connect, then the domain id defined in the domain connection settings does not match the remote domain. If this happens on a reconnect, then the remote domain has been reset for some reason. • Resolution: Carefully verify the connection settings. • Category: InvalidGivenCurrentSystemStateOther • Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message • Scaladocs: DOMAIN_ID_MISMATCH #### SERVICE_AGREEMENT_ACCEPTANCE_FAILED¶ • Explanation: This error indicates that the domain requires the participant to accept a service agreement before connecting to it. • Resolution: Use the commands$participant.domains.get_agreement and \$participant.domains.accept_agreement to accept the agreement.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

### 1.5.1.3. ConnectionErrors¶

#### DOMAIN_IS_NOT_AVAILABLE¶

• Explanation: This error results if the GRPC connection to the domain service fails with GRPC status UNAVAILABLE.

• Resolution: Check your connection settings and ensure that the domain can really be reached.

• Category: TransientServerFailure

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message

#### FAILED_TO_CONNECT_TO_SEQUENCER¶

• Explanation: This error indicates that the participant failed to connect to the sequencer.

• Resolution: Inspect the provided reason.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

#### GRPC_CONNECTION_FAILURE¶

• Explanation: This error indicates that the participant failed to connect due to a general GRPC error.

• Resolution: Inspect the provided reason and contact support.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

#### PARTICIPANT_IS_NOT_ACTIVE¶

• Explanation: This error indicates that the connecting participant has either not yet been activated by the domain operator. If the participant was previously successfully connected to the domain, then this error indicates that the domain operator has deactivated the participant.

• Resolution: Contact the domain operator and inquire the permissions your participant node has on the given domain.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

• Explanation: This error indicates that the admin workflow package could not be vetted. The admin workflows is a set of packages that are pre-installed and can be used for administrative processes. The error can happen if the participant is initialised manually but is missing the appropriate signing keys or certificates in order to issue new topology transactions within the participants namespace. The admin workflows can not be used until the participant has vetted the package.

• Resolution: This error can be fixed by ensuring that an appropriate vetting transaction is issued in the name of this participant and imported into this participant node. If the corresponding certificates have been added after the participant startup, then this error can be fixed by either restarting the participant node, issuing the vetting transaction manually or re-uploading the Dar (leaving the vetAllPackages argument as true)

• Conveyance: This error is logged with log-level WARN on the server side.

### 1.7.1. DatabaseErrors¶

#### INDEX_DB_INVALID_RESULT_SET¶

• Explanation: This error occurs if the result set returned by a query against the Index database is invalid.

• Resolution: Contact support.

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

#### INDEX_DB_SQL_NON_TRANSIENT_ERROR¶

• Explanation: This error occurs if a non-transient error arises when executing a query against the index database.

• Resolution: Contact the participant operator.

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

#### INDEX_DB_SQL_TRANSIENT_ERROR¶

• Explanation: This error occurs if a transient error arises when executing a query against the index database.

• Resolution: Re-submit the request.

• Category: TransientServerFailure

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status UNAVAILABLE including a detailed error message

### 1.8. PruningServiceError¶

#### INTERNAL_PRUNING_ERROR¶

• Explanation: Pruning has failed because of an internal server error.

• Resolution: Identify the error in the server log.

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

#### NON_CANTON_OFFSET¶

• Explanation: The supplied offset has an unexpected lengths.

• Resolution: Ensure the offset has originated from this participant and is 9 bytes in length.

• Category: InvalidIndependentOfSystemState

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

#### PRUNING_NOT_SUPPORTED_IN_COMMUNITY_EDITION¶

• Explanation: Pruning is not supported in the Community Edition.

• Resolution: Upgrade to the Enterprise Edition.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

#### UNSAFE_TO_PRUNE¶

• Explanation: Pruning is not possible at the specified offset at the current time.

• Resolution: Specify a lower offset or retry pruning after a while.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

### 1.9. CantonPackageServiceError¶

#### PACKAGE_REMOVAL_ERROR¶

• Explanation: Errors raised by the Package Service on package removal.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

### 1.10. ParticipantReplicationServiceError¶

#### PARTICIPANT_REPLICATION_INTERNAL_ERROR¶

• Explanation: Internal error emitted upon internal participant replication errors

• Resolution: Contact support

• Category: SystemInternalAssumptionViolated

• Conveyance: This error is logged with log-level ERROR on the server side. This error is exposed on the API with grpc-status INTERNAL without any details due to security reasons

#### PARTICIPANT_REPLICATION_NOT_SUPPORTED_BY_STORAGE¶

• Explanation: Error emitted if the supplied storage configuration does not support replication.

• Resolution: Use a participant storage backend supporting replication.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

### 2. EthereumErrors¶

#### ATTEMPT_TO_CHANGE_IMMUTABLE_VALUE¶

• Explanation: The sequencer smart contract has detected that a value that is immutable after being set for the first time (either the signing tolerance or the topology manager ID) was attempted to be changed. Most frequently this error occurs during testing when a Canton Ethereum sequencer process without persistence is restarted while pointing to the same smart sequencer contract. An Ethereum sequencer attempts to set the topology manager ID during initialization, however, without persistence the topology manager ID is randomly regenerated on the restart which leads to the sequencer attempting to change the topology manager ID in the sequencer smart contract.

• Resolution: Deploy a new instance of the sequencer contract (Console command ethereum.deploy_sequencer_contract) and configure the Ethereum sequencer to use that instance. If the errors occur because an Ethereum sequencer process is restarted without persistence, deploy a fresh instance of the sequencer contract and configure persistence for restarts.

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message

• Explanation: This error is logged when the sequencer is currently processing blocks that are very far behind the head of the blockchain of the connected Ethereum network. The Ethereum sequencer won’t observe new transactions in the blockchain until it has caught up to the head. This may take a long time depending on the blockchain length and number of Canton transaction in the blocks. Empirically, we have observed that the Canton sequencer processes roughly 500 empty blocks/second. This may vary strongly for non-empty blocks. The sequencer logs once it has caught up to within blocksBehindBlockchainHead blocks behind the blockchain head.

• Resolution: Change the configuration of blockToReadFrom for the Ethereum sequencer when working with an existing (not fresh) Ethereum network. Alternatively, wait until the sequencer has caught up to the head of the blockchain.

• Conveyance: This error is logged with log-level WARN on the server side.

#### NOT_FREE_GAS_NETWORK¶

• Explanation: This error is logged when during setup the sequencer detects that it isn’t connected to a free-gas network. This usually leads to transactions silently being dropped by Ethereum nodes. You should only use a non-free-gas network, if you have configured an Ethereum wallet for the sequencer to use and have given it gas.

• Resolution: Change the configuration of the Ethereum network to a free-gas network.

• Category: InvalidIndependentOfSystemState

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

### 3. ConfigErrors¶

#### CANNOT_PARSE_CONFIG_FILES¶

• Explanation: This error is usually thrown because a config file doesn’t contain configs in valid HOCON format. The most common cause of an invalid HOCON format is a forgotten bracket.

• Resolution: Make sure that all files are in valid HOCON format.

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

• Explanation: This error is usually thrown when Canton can’t find a given configuration file.

• Resolution: Make sure that the path and name of all configuration files is correctly specified.

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

#### CONFIG_SUBSTITUTION_ERROR¶

• Resolution: A common cause of this error is attempting to use an environment variable that isn’t defined within a config-file.

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

#### CONFIG_VALIDATION_ERROR¶

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

#### GENERIC_CONFIG_ERROR¶

• Resolution: In general, this can be one of many errors since this is the ‘miscellaneous category’ of configuration errors. One of the more common errors in this category is an ‘unknown key’ error. This error usually means that a keyword that is not valid (e.g. it may have a typo ‘bort’ instead of ‘port’), or that a valid keyword at the wrong part of the configuration hierarchy was used (e.g. to enable database replication for a participant, the correct configuration is canton.participants.participant2.replication.enabled = true and not canton.participants.replication.enabled = true). Please refer to the scaladoc of either CantonEnterpriseConfig or CantonCommunityConfig (depending on whether the community or enterprise version is used) to find the valid configuration keywords and the correct position in the configuration hierarchy.

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

#### NO_CONFIG_FILES¶

• Category: InvalidIndependentOfSystemState

• Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails

### 4. CommandErrors¶

#### CONSOLE_COMMAND_TIMED_OUT¶

• Category: SystemInternalAssumptionViolated

• Conveyance: These errors are shown as errors on the console.

#### NODE_NOT_STARTED¶

• Category: InvalidGivenCurrentSystemStateOther

• Conveyance: These errors are shown as errors on the console.

### 5. DatabaseStorageError¶

• Explanation: This error indicates that degradation of database storage components.

• Resolution: Inspect error message for details.

• Conveyance: This error is logged with log-level WARN on the server side.

### 6. ProtoDeserializationError¶

#### PROTO_DESERIALIZATION_FAILURE¶

• Explanation: This error indicates that an incoming administrative command could not be processed due to a malformed message.

• Resolution: Inspect the error details and correct your application

• Category: InvalidIndependentOfSystemState

• Conveyance: This error is logged with log-level INFO on the server side. This error is exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message

### 7. ResilientSequencerSubscription¶

#### SEQUENCER_SUBSCRIPTION_LOST¶

• Explanation: This warning is logged when a sequencer subscription is interrupted. The system will keep on retrying to reconnect indefinitely.

• Resolution: Monitor the situation and contact the server operator if the issues does not resolve itself automatically.

• Conveyance: This error is logged with log-level WARN on the server side.

### 8. Clock¶

#### SYSTEM_CLOCK_RUNNING_BACKWARDS¶

• Explanation: This error is emitted if the unique time generation detects that the host system clock is lagging behind the unique time source by more than a second. This can occur if the system processes more than 2e6 events per second (unlikely) or when the underlying host system clock is running backwards.

• Resolution: Inspect your host system. Generally, the unique time source is not negatively affected by a clock moving backwards and will keep functioning. Therefore, this message is just a warning about something strange being detected.