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.

Machine Readable Information

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. ParticipantErrorGroup

1.1. Errors

ACS_COMMITMENT_INTERNAL_ERROR

Explanation: This error indicates that there was an internal error within the ACS commitment processing.
Category: SystemInternalAssumptionViolated$
Conveyance: This error is logged with log-level ERROR on the server side.
Resolution: Inspect error message for details.
Scaladoc

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.
Category: BackgroundProcessDegradationWarning$
Conveyance: This error is logged with log-level WARN on the server side.
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.
Scaladoc
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.
Category: BackgroundProcessDegradationWarning$
Conveyance: This error is logged with log-level WARN on the server side.
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.
Scaladoc

1.2. TopologyManagerError

CERTIFICATE_GENERATION_ERROR

Explanation: This error indicates that the desired certificate could not be created.
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
Resolution: Inspect the underlying error for details.
Scaladoc
DUPLICATE_TOPOLOGY_TRANSACTION

Explanation: This error indicates that a transaction has already been added previously.
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
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.
Scaladoc
INVALID_TOPOLOGY_TX_SIGNATURE_ERROR

Explanation: This error indicates that the uploaded signed transaction contained an invalid signature.
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
Resolution: Ensure that the transaction is valid and uses a crypto version understood by this participant.
Scaladoc
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.
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
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.
Scaladoc
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.
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
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.
Scaladoc
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.
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
Resolution: Upload the public key to the public key store using $node.keys.public.load(.) before retrying.
Scaladoc
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.
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
Resolution: Add the `force = true` flag to your command if you are really sure what you are doing.
Scaladoc
SECRET_KEY_NOT_IN_STORE

Explanation: This error indicates that the secret key with the respective fingerprint can not be found.
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
Resolution: Ensure you only use fingerprints of secret keys stored in your secret key store.
Scaladoc
TOPOLOGY_MANAGER_INTERNAL_ERROR

Explanation: This error indicates that there was an internal error within the topology manager.
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
Resolution: Inspect error message for details.
Scaladoc
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.
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
Resolution: Your intended change is already in effect.
Scaladoc
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.
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
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.
Scaladoc

1.2.1. DomainTopologyManagerError

ALIEN_DOMAIN_ENTITIES

Explanation: This error is returned if a transaction attempts to add keys for alien domain entities to this domain topology manager.
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
Resolution: Use a participant topology manager if you want to manage foreign domain keys
Scaladoc
FAILED_TO_ADD_MEMBER

Explanation: This error indicates an external issue with the member addition hook.
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
Resolution: Consult the error details.
Scaladoc
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.
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
Resolution: Register the necessary keys and try again.
Scaladoc
WRONG_DOMAIN

Explanation: This error is returned if a transaction restricted to a domain should be added to another 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
Resolution: Recreate the content of the transaction with a correct domain identifier.
Scaladoc

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.
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
Resolution: Ensure that the package exists locally before issuing such a transaction.
Scaladoc
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.
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
Resolution: Set force=true if you really know what you are doing.
Scaladoc
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.
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
Resolution: Set force=true if you really know what you are doing.
Scaladoc
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.
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
Resolution: Vet the dependencies first and then repeat your attempt.
Scaladoc
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.
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
Resolution: Initialise the participant and retry.
Scaladoc

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.
Scaladoc
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.
Scaladoc

1.3. TransactionErrorGroup

1.3.1. LedgerApiErrors

LEDGER_API_INTERNAL_ERROR

Explanation: This error occurs if there was an unexpected error within the interpreter
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
Resolution: Contact support.
Scaladoc
NON_HEXADECIMAL_OFFSET

Explanation: The supplied offset could not be converted to a binary offset.
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
Resolution: Ensure the offset is specified as a hexadecimal string.
Scaladoc

1.3.1.1. Package

ALLOWED_LANGUAGE_VERSIONS

Explanation: This error indicates that the uploaded dar is based on an unsupported language 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
Resolution: Use a Dar compiled with a language version that this participant supports.
Scaladoc
MISSING_PACKAGE

Explanation: This error occurs if the Daml transaction is referring to a package which is not known to the participant.
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
Resolution: Upload the necessary Dars to the participant node.
Scaladoc
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.
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
Resolution: Contact support.
Scaladoc

1.3.1.2. PreprocessingErrors

COMMAND_PREPROCESSING_FAILED

Explanation: This error occurs if a command fails during interpreter pre-processing.
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
Resolution: Inspect error details and correct your application.
Scaladoc

1.3.1.3. InterpreterErrors

CONTRACT_NOT_ACTIVE

Explanation: This error occurs if an exercise or fetch happens on a transaction-locally consumed 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
Resolution: This error indicates an application error.
Scaladoc
DAML_AUTHORIZATION_ERROR

Explanation: This error occurs if the 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.
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
Resolution: This error type occurs if there is an application error.
Scaladoc
DAML_INTERPRETATION_ERROR

Explanation: This error occurs if the Daml transaction failed during interpretation.
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
Resolution: This error type occurs if there is an application error.
Scaladoc
DAML_INTERPRETER_INVALID_ARGUMENT

Explanation: This error occurs if the Daml transaction failed during interpretation due to an invalid argument.
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
Resolution: This error type occurs if there is an application error.
Scaladoc
DUPLICATE_CONTRACT_KEY_DURING_INTERPRETATION

Explanation: This error signals that within the transaction we got to a point where two contracts with the same key were active.
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
Resolution: This error indicates an application error.
Scaladoc

1.3.1.3.1. LookupErrors

CONTRACT_KEY_NOT_FOUND

Explanation: This error occurs if the Damle interpreter can not 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 the key has already being archived.
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
Resolution: This error type occurs if there is contention on a contract.
Scaladoc
CONTRACT_NOT_FOUND

Explanation: This error occurs if the Damle interpreter 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.
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
Resolution: This error type occurs if there is contention on a contract.
Scaladoc

1.3.1.4. CommandPreparation

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. However, it can also happen with contract keys.
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
Resolution: Retry the transaction
Scaladoc

1.3.1.5. CommandValidation

INVALID_ARGUMENT

Explanation: This error is emitted, when a submitted ledger Api command contained an invalid argument.
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
Resolution: Inspect the reason given and correct your application.
Scaladoc
INVALID_FIELD

Explanation: This error is emitted, when a submitted ledger Api command contained a field value that could not be properly understood
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
Resolution: Inspect the reason given and correct your application.
Scaladoc
LEDGER_ID_MISMATCH

Explanation: Every ledger Api command contains a ledger-id which is verifying against the running ledger. This error indicates that the provided ledger-id does not match the expected one.
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
Resolution: Ensure that your application is correctly configured to use the correct ledger.
Scaladoc
MISSING_FIELDS

Explanation: This error is emitted, when a submitted ledger Api command could not be successfully deserialized due to mandatory fields not being set.
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
Resolution: Inspect the reason given and correct your application.
Scaladoc

1.3.1.6. AuthorizationChecks

PERMISSION_DENIED

Explanation: This rejection is given if the supplied JWT 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.
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
Resolution: Inspect your command and your token, or ask your participant operator for an explanation why this command failed.
Scaladoc
UNAUTHENTICATED

Explanation: This rejection is given if the submitted command does not contain a JWT token on a participant enforcing JWT authentication.
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
Resolution: Ask your participant operator to provide you with an appropriate JWT token.
Scaladoc

1.3.2. 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.
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
Resolution: Inspect the message and your topology and ensure appropriate permissions exist.
Scaladoc
ROUTING_INTERNAL_ERROR

Explanation: This error indicates an internal error in the Canton domain router.
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
Resolution: Please contact support.
Scaladoc

1.3.2.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.
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
Resolution: Ensure that there is such a domain, as Canton requires a domain where all informees are present.
Scaladoc
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.
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
Resolution: Check the status of your domain connections.
Scaladoc
NO_COMMON_DOMAIN

Explanation: This error indicates that there is no common domain to which all submitters can submit and all informees are connected.
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
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.
Scaladoc
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.
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
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.
Scaladoc
SUBMITTER_ALWAYS_STAKEHOLDER

Explanation: This error indicates that the transaction requires contract transfers for which the submitter must be a stakeholder.
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
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.
Scaladoc
UNKNOWN_INFORMEES

Explanation: This error indicates that the transaction is referring to some informees that are not known on any connected 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
Resolution: Check the list of submitted informees and check if your participant is connected to the domains you are expecting it to be.
Scaladoc

1.3.2.2. MalformedInputErrors

INVALID_DOMAIN_ALIAS

Explanation: The WorkflowID defined in the transaction metadata is not a valid 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
Resolution: Check that the workflow ID (if specified) corresponds to a valid domain alias. A typical rejection reason is a too-long domain alias.
Scaladoc
INVALID_SUBMITTER

Explanation: The party defined as a submitter can not be parsed into a valid Canton party.
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
Resolution: Check that you only use correctly setup party names in your application.
Scaladoc

1.3.2.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.
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
Resolution: Set canton.parameters.enable-preview-features = yes
Scaladoc
SUBMISSION_DOMAIN_NOT_READY

Explanation: This error indicates that the transaction should be submitted to a domain which is not connected or not configured.
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
Resolution: Ensure that the domain is correctly connected.
Scaladoc

1.3.3. CommandDeduplicationError

COMMAND_ALREADY_EXISTS

Explanation: There is an earlier accepting completion that falls into the submission’s deduplication period. The metadata key ``earlier_completion_offset`` contains the completion offset of the conflicting completion.
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
Resolution: To bypass the command deduplication check, the application should pick a fresh command ID.
Scaladoc
DEDUPLICATION_PERIOD_STARTS_TOO_EARLY

Explanation: The command deduplication period starts too early. The metadata key ``earliest_known_offset`` contains the earliest completion offset that can currently be used for deduplication.
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
Resolution: Resubmit with a shorter deduplication period.
Scaladoc
MALFORMED_DEDUPLICATION_OFFSET

Explanation: The specified deduplication offset is syntactically malformed.
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
Resolution: Use a deduplication offset that was produced by this participant node.
Scaladoc

1.3.4. SyncServiceInjectionError

COMMAND_INJECTION_FAILURE

Explanation: This errors occurs if an internal error results in an exception.
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
Resolution: Contact support.
Scaladoc
NODE_IS_PASSIVE_REPLICA

Explanation: This error results if a command is submitted to the passive 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
Resolution: Send the command to the active replica.
Scaladoc
NOT_CONNECTED_TO_ANY_DOMAIN

Explanation: This errors results if a command is submitted to a participant that is not connected to any 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
Resolution: Connect your participant to the domain where the given parties are hosted.
Scaladoc

1.3.5. SubmissionErrors

DOMAIN_BACKPRESSURE

Explanation: This error occurs when the sequencer refuses to accept a command due to backpressure.
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
Resolution: Wait a bit and retry, preferably with some backoff factor.
Scaladoc
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
Scaladoc
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.
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
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.
Scaladoc
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.
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
Resolution: Ensure that the receiving participant uploads and vets the respective package.
Scaladoc
PARTICIPANT_BACKPRESSURE

Explanation: This error occurs when the participant rejects a command due to excessive load. Load can be caused as follows: 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.
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
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.
Scaladoc
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
Scaladoc
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
Scaladoc
SUBMISSION_ALREADY_IN_FLIGHT

Explanation: This error occurs if another command submission with the same change ID (application ID, command ID, actAs) is already being processed.
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
Resolution: Listen to the command completion stream until a completion for the in-flight command submission is published. Alternatively, resubmit the command after a while. If the in-flight submission has finished successfully by then, this will return more detailed information about the earlier one via the deduplication guarantee. If the in-flight submission has failed by then, the resubmission will attempt to record the new transaction on the ledger.
Scaladoc
SUBMISSION_DURING_SHUTDOWN

Explanation: This error occurs when a command is submitted while the system is performing a shutdown.
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
Resolution: Assuming that the participant will restart or failover eventually, retry in a couple of seconds.
Scaladoc

1.3.6. LocalReject

1.3.6.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.
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
Resolution: This indicates a race condition due to a in-flight topology change, or malicious or faulty behaviour.
Scaladoc
LOCAL_VERDICT_DETECTED_MULTIPLE_CONFIRMATION_POLICIES

Explanation: This rejection is made by a participant if a transaction uses different confirmation policies per view.
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
Resolution: This indicates either malicious or faulty behaviour.
Scaladoc
LOCAL_VERDICT_EMPTY_REJECTION

Explanation: This rejection is emitted by a participant if it receives an aggregated reject without any reason.
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
Resolution: This indicates either malicious or faulty mediator.
Scaladoc
LOCAL_VERDICT_FAILED_MODEL_CONFORMANCE_CHECK

Explanation: This rejection is made by a participant if a transaction fails a model conformance check.
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
Resolution: This indicates either malicious or faulty behaviour.
Scaladoc
LOCAL_VERDICT_MALFORMED_PAYLOAD

Explanation: This rejection is made by a participant if a view of the transaction is malformed.
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
Resolution: This indicates either malicious or faulty behaviour.
Scaladoc

1.3.6.2. ConsistencyRejections

LOCAL_VERDICT_CREATES_EXISTING_CONTRACTS

Explanation: This error indicates that the transaction would create already existing contracts.
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
Resolution: This error indicates either faulty or malicious behaviour.
Scaladoc
LOCAL_VERDICT_DUPLICATE_KEY

Explanation: If the participant is connected to a domain with unique contract key support, this error will indicate that a transaction would create a unique key which 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
Resolution: It depends on your use case and application whether and when retrying makes sense or not.
Scaladoc
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.
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
Resolution: Inspect your contract state and try a different transaction.
Scaladoc
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.
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
Resolution: Retry the transaction
Scaladoc
LOCAL_VERDICT_LOCKED_KEYS

Explanation: The transaction is referring to locked keys which are in the process of being modified by another 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
Resolution: Retry the transaction
Scaladoc

1.3.6.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.
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
Resolution: For long-running transactions, specify a ledger time with the command submission. For short-running transactions, simply retry.
Scaladoc
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.
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
Resolution: For long-running transactions, adjust the ledger time bounds used with the command submission. For short-running transactions, simply retry.
Scaladoc
LOCAL_VERDICT_TIMEOUT

Explanation: This rejection is sent if the participant locally determined a timeout.
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
Resolution: Resubmit your transaction.
Scaladoc

1.3.6.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
Scaladoc
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
Scaladoc
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
Scaladoc
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
Scaladoc

1.3.6.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.
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
Resolution: Depending on your use-case and your expectation, retry the transaction.
Scaladoc

1.3.7. 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.
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
Resolution: Check that all involved participants are available and not overloaded.
Scaladoc

1.3.7.1. 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.
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
Resolution: This error can happen either if the transaction is racing with a topology state change, or due to malicious or faulty behaviour.
Scaladoc
MEDIATOR_SAYS_INVALID_ROOT_HASH_MESSAGES

Explanation: This rejection indicates that a submitter has sent a view with invalid root hash messages.
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
Resolution: This error can happen either if the transaction is racing with a topology state change, or due to malicious or faulty behaviour.
Scaladoc

1.3.7.2. MaliciousSubmitter

MEDIATOR_SAYS_NOT_ENOUGH_CONFIRMING_PARTIES

Explanation: This rejection indicates that a submitter has sent a manipulated view.
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
Resolution: Investigate whether the submitter is faulty or malicious.
Scaladoc
MEDIATOR_SAYS_VIEW_THRESHOLD_BELOW_MINIMUM_THRESHOLD

Explanation: This rejection indicates that a submitter has sent a manipulated view.
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
Resolution: Investigate whether the submitter is faulty or malicious.
Scaladoc

1.4. 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
Scaladoc
SYNC_SERVICE_DOMAIN_DISABLED_US

Explanation: This error is logged when the synchronization service shuts down because the remote domain has disabled this participant.
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
Resolution: Contact the domain operator and inquire why you have been booted out.
Scaladoc
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)
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
Resolution: Please contact support and provide the failure reason.
Scaladoc
SYNC_SERVICE_INTERNAL_ERROR

Explanation: This error indicates an internal issue.
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
Resolution: Please contact support and provide the failure reason.
Scaladoc
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
Scaladoc

1.4.1. DomainRegistryError

DOMAIN_REGISTRY_INTERNAL_ERROR

Explanation: This error indicates that there has been an internal error noticed by Canton.
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
Resolution: Contact support and provide the failure reason.
Scaladoc

1.4.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.
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
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.
Scaladoc
DOMAIN_MESSAGE_SIZE_EXCEEDS_PARTICIPANT_SETTINGS

Explanation: This error indicates that the participant is trying to connect to a domain that might send data which exceed the locally configured max 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
Resolution: Reconfigure the canton.participants.$participant.max-inbound-message-size setting and restart.
Scaladoc
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
Scaladoc
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.
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
Resolution: Use isolated participants for domains that require unique keys.
Scaladoc
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
Scaladoc

1.4.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.
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
Resolution: Carefully verify the connection settings.
Scaladoc
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.
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
Resolution: Consult the error message and adjust the supported crypto schemes of this participant.
Scaladoc
DOMAIN_HANDSHAKE_FAILED

Explanation: This error indicates that the participant to domain handshake has failed.
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
Resolution: Inspect the provided reason for more details and contact support.
Scaladoc
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.
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
Resolution: Carefully verify the connection settings.
Scaladoc
SERVICE_AGREEMENT_ACCEPTANCE_FAILED

Explanation: This error indicates that the domain requires the participant to accept a service agreement before connecting to it.
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
Resolution: Use the commands $participant.domains.get_agreement and $participant.domains.accept_agreement to accept the agreement.
Scaladoc

1.4.1.3. ConnectionErrors

DOMAIN_IS_NOT_AVAILABLE

Explanation: This error results if the GRPC connection to the domain service fails with GRPC status UNAVAILABLE.
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
Resolution: Check your connection settings and ensure that the domain can really be reached.
Scaladoc
FAILED_TO_CONNECT_TO_SEQUENCER

Explanation: This error indicates that the participant failed to connect to the sequencer.
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
Resolution: Inspect the provided reason.
Scaladoc
GRPC_CONNECTION_FAILURE

Explanation: This error indicates that the participant failed to connect due to a general GRPC 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
Resolution: Inspect the provided reason and contact support.
Scaladoc
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.
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
Resolution: Contact the domain operator and inquire the permissions your participant node has on the given domain.
Scaladoc

1.5. AdminWorkflowServices

CAN_NOT_AUTOMATICALLY_VET_ADMIN_WORKFLOW_PACKAGE

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.
Category: BackgroundProcessDegradationWarning$
Conveyance: This error is logged with log-level WARN on the server side.
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)
Scaladoc

1.6. PackageServiceError

DAR_NOT_SELF_CONSISTENT

Explanation: This error indicates that the uploaded Dar is broken because it is missing internal dependencies.
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
Resolution: Contact the supplier of the Dar.
Scaladoc
DAR_VALIDATION_ERROR

Explanation: This error indicates that the validation of the uploaded dar failed.
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
Resolution: Inspect the error message and contact support.
Scaladoc
PACKAGE_SERVICE_INTERNAL_ERROR

Explanation: This error indicates an internal issue within the package service.
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
Resolution: Inspect the error message and contact support.
Scaladoc

1.6.1. Reading

DAR_PARSE_ERROR

Explanation: This error indicates that the content of the Dar file could not be parsed successfully.
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
Resolution: Inspect the error message and contact support.
Scaladoc
INVALID_DAR

Explanation: This error indicates that the supplied dar file was invalid.
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
Resolution: Inspect the error message for details and contact support.
Scaladoc
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.
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
Resolution: Inspect error message for details and change the file name accordingly
Scaladoc
INVALID_LEGACY_DAR

Explanation: This error indicates that the supplied zipped dar is an unsupported legacy 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
Resolution: Please use a more recent dar version.
Scaladoc
INVALID_ZIP_ENTRY

Explanation: This error indicates that the supplied zipped dar file was invalid.
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
Resolution: Inspect the error message for details and contact support.
Scaladoc
ZIP_BOMB

Explanation: This error indicates that the supplied zipped dar is regarded as zip-bomb.
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
Resolution: Inspect the dar and contact support.
Scaladoc

1.7. PruningServiceError

INTERNAL_PRUNING_ERROR

Explanation: Pruning has failed because of an internal server error.
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
Resolution: Identify the error in the server log.
Scaladoc
NON_CANTON_OFFSET

Explanation: The supplied offset has an unexpected lengths.
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
Resolution: Ensure the offset has originated from this participant and is 9 bytes in length.
Scaladoc
PRUNING_NOT_SUPPORTED_IN_COMMUNITY_EDITION

Explanation: Pruning is not supported in the Community 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
Resolution: Upgrade to the Enterprise Edition.
Scaladoc
UNSAFE_TO_PRUNE

Explanation: Pruning is not possible at the specified offset at the current time.
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
Resolution: Specify a lower offset or retry pruning after a while.
Scaladoc

1.8. ParticipantReplicationServiceError

PARTICIPANT_REPLICATION_INTERNAL_ERROR

Explanation: Internal error emitted upon internal participant replication errors
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
Resolution: Contact support
Scaladoc
PARTICIPANT_REPLICATION_NOT_SUPPORTED_BY_STORAGE

Explanation: Error emitted if the supplied storage configuration does not support 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
Resolution: Use a participant storage backend supporting replication.
Scaladoc

2. 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.
Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
Resolution: Make sure that all files are in valid HOCON format.
Scaladoc
CANNOT_READ_CONFIG_FILES

Explanation: This error is usually thrown when Canton can't find a given configuration file.
Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
Resolution: Make sure that the path and name of all configuration files is correctly specified.
Scaladoc
CONFIG_SUBSTITUTION_ERROR

Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
Resolution: A common cause of this error is attempting to use an environment variable that isn't defined within a config-file.
Scaladoc
CONFIG_VALIDATION_ERROR

Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
Scaladoc
GENERIC_CONFIG_ERROR

Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
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.
Scaladoc
NO_CONFIG_FILES

Explanation: No configuration files were given to Canton when attempting to start it
Category: InvalidIndependentOfSystemState$
Conveyance: Config errors are logged and output to stdout if starting Canton with a given configuration fails
Resolution: Specify configuration files via '-c, --config <file1>,<file2>,...'
Scaladoc

3. CommandErrors

CONSOLE_COMMAND_INTERNAL_ERROR

Category: SystemInternalAssumptionViolated$
Conveyance: These errors are shown as errors on the console.
Scaladoc
CONSOLE_COMMAND_TIMED_OUT

Category: SystemInternalAssumptionViolated$
Conveyance: These errors are shown as errors on the console.
Scaladoc
NODE_NOT_STARTED

Category: InvalidGivenCurrentSystemStateOther$
Conveyance: These errors are shown as errors on the console.
Scaladoc

4. ProtoDeserializationError

PROTO_DESERIALIZATION_FAILURE

Explanation: This error indicates that an incoming administrative command could not be processed due to a malformed message.
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
Resolution: Inspect the error details and correct your application
Scaladoc

5. ResilientSequencerSubscription

SEQUENCER_SUBSCRIPTION_LOST

Explanation: This warning is logged when a sequencer subscription is interrupted. The system will keep on retrying to reconnect indefinitely.
Category: BackgroundProcessDegradationWarning$
Conveyance: This error is logged with log-level WARN on the server side.
Resolution: Monitor the situation and contact the server operator if the issues does not resolve itself automatically.
Scaladoc

6. 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.
Category: BackgroundProcessDegradationWarning$
Conveyance: This error is logged with log-level WARN on the server side.
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.
Scaladoc