Error Code Reference - Canton Network Docs

Canton uses a structured error code system across all components. Every error logged or returned via the API follows the format ERROR_CODE_ID(category_id, correlation_id_prefix): human-readable message. This page explains how to read these errors, which categories require operator action, and what the most common operational errors mean. For gRPC error codes encountered during application development, see the AppDev error codes reference.

Reading Error Codes in Logs

Log Levels

Canton uses log levels consistently:

INFO — user errors where the request failed but the system remains healthy. Most category 1, 2, 8, 9, 10, 11, and 12 errors log at this level.
WARN — system degradation or unusual behavior that may need attention. Security alerts (category 5) and degradation warnings (category 13) log here.
ERROR — internal errors where the system is not behaving correctly and requires immediate attention. Category 4 (SystemInternalAssumptionViolated) errors log here.

As an operator, you should set up alerting on WARN and ERROR level messages. INFO-level error codes are typically transient or caused by client-side issues, though persistent INFO-level errors (such as repeated SEQUENCER_REQUEST_FAILED) can signal connectivity problems that need investigation.

Error Categories

This section was copied from existing reviewed documentation. Source: manual/build/3.5/reference/app-dev/error-codes.rst Reviewers: Skip this section. Remove markers after final approval.

Error Categories The error categories allow you to group errors such that application logic can be built to automatically deal with errors and decide whether to retry a request or escalate to the operator. A full list of error categories is documented here.

Machine Readable Information

Every error on the API is constructed to allow automated and manual error handling. First, the error category maps to exactly one gRPC status code. Second, every error description (of the corresponding StatusRuntimeException.Status) starts with the error information (SOMETHING_NOT_SO_GOOD_HAPPENED(CN,x)), separated from a human readable description by a colon (”:”). The rest of the description is targeted to 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, synchronizer) 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 <tracing>, 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. As with Daml error codes described above, many errors include more information, but there is no guarantee 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. For 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.

Example

If an application submits a Daml transaction that exceeds the size limits enforced on a synchronizer, the command will be rejected. Using the logs of one of our test cases, the participant node will log the following message:

2022-04-26 11:37:54,584 [GracefulRejectsIntegrationTestDefault-env-execution-context-30] INFO  c.d.c.p.p.TransactionProcessingSteps:participant=participant1/synchronizer=da tid:13617c1bda402e54e016a6a17637cb20 - SEQUENCER_REQUEST_FAILED(2,13617c1b): Failed to send command err-context:{location=TransactionProcessingSteps.scala:449, sendError=RequestInvalid(Batch size (85134 bytes) is exceeding maximum size (27000 bytes) for synchronizer da::12201253c344...)}

The machine-readable part of the error message appears as SEQUENCER_REQUEST_FAILED(2,13617c1b), mentioning the error id SEQUENCER_REQUEST_FAILED, the category ContentionOnSharedResources with id=2, and the correlation identifier 13617c1b. Please note that there is no guarantee on the name of the logger that is emitting the given error, as this name is internal and subject to change. The human-readable part of the log message should not be parsed, as we might subsequently improve the text. The client will receive the error information as a Grpc error:

2022-04-26 11:37:54,923 [ScalaTest-run-running-GracefulRejectsIntegrationTestDefault] ERROR  c.d.c.i.EnterpriseEnvironmentDefinition$$anon$3 - Request failed for participant1.
    GrpcRequestRefusedByServer: ABORTED/SEQUENCER_REQUEST_FAILED(2,13617c1b): Failed to send command
    Request: SubmitAndWaitTransactionTree(actAs = participant1::1220baa5cd30..., commandId = '', workflowId = '', submissionId = '', deduplicationPeriod = None(), ledgerId = 'participant1', commands= ...)
    CorrelationId: 13617c1bda402e54e016a6a17637cb20
    RetryIn: 1 second
    Context: HashMap(participant -> participant1, test -> GracefulRejectsIntegrationTestDefault, synchronizer -> da, sendError -> RequestInvalid(Batch size (85134 bytes) is exceeding maximum size (27000 bytes) for synchronizer da::12201253c344...), definite_answer -> true)

Note that the second log is created by Daml tooling that prints the Grpc Status into the log files during tests. The actual Grpc error would be received by the application and would not be logged by the participant node in the given form.

Error Categories Inventory

The error categories allow you 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.

Error Codes Inventory

1. GrpcErrors

ABORTED_DUE_TO_SHUTDOWN

Explanation: This error is returned when processing of the request was aborted due to the node shutting down.
Resolution: Retry the request against an active and available node.
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

SERVER_OVERLOADED

Explanation: The node is at capacity and therefore limits the number of parallel requests.
Resolution: Retry with exponential backoff.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

2. AuthorizationChecksErrors

ACCESS_TOKEN_EXPIRED

Explanation: This rejection is given when a valid JWT token used for some period of time expires.
Resolution: Ask your participant operator or IDP provider to give you an appropriate JWT token.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

INVALID_TOKEN

Explanation: This error is emitted when a submitted ledger API command contains an invalid token.
Resolution: Inspect the reason given and correct your application.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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. It is exposed on the API with grpc-status PERMISSION_DENIED without any details for security reasons.

STALE_STREAM_AUTHORIZATION

Explanation: The stream was aborted because the authenticated user’s rights changed, and the user might thus no longer be authorized to this stream.
Resolution: The application should automatically retry fetching the stream. It will either succeed, or fail with an explicit denial of authentication or permission.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

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 or IDP provider to give you an appropriate JWT token.
Category: AuthInterceptorInvalidAuthenticationCredentials
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status UNAUTHENTICATED without any details for security reasons.

3. ParticipantErrorGroup

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

3.1.1. MismatchError

ACS_COMMITMENT_ALARM

Explanation: The participant has detected that another node is behaving maliciously. This warning occurs in several cases. First, it occurs when the ACS commitment received from a counter-participant has an invalid signature. It might be that the counter-participant itself is malicious and purposefully added a wrong signature, or that someone else modified the signed commitment sent correctly by the counter-participant, or even crafted a message in the name of a counter-participant. Second, this alarm occurs when the participant receives two correctly signed but different commitments from the same counter-participant covering the same interval. A correct counter-participant never sends that.
Resolution: Contact support.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

ACS_COMMITMENT_MISMATCH

Explanation: This error code indicates a commitment mismatch between the participant and one or more counter-participants. Between honest participants a fork should never happen, however, misbehavior, bugs or manual changes to contract stores using the repair service can lead to forks. A fork means that one or more common contracts are active on the participant, but not on its counter-participants, or vice versa. Disagreeing participants will have different local verdicts on the conformance checks of transactions using disputed contracts. As long as these contracts are active, the fork exists, but if the contracts get deactivated as part of their lifecycle, then the fork automatically “resolves itself”. A participant node operator can also fix a fork manually via repair commands.
Resolution: Please refer to the runbook on inspecting commitment mismatches in order to determine the cause of the mismatch together with the counter-participant node. Then repair the store of this participant and/or the store of the counter-participant.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

ACS_MISMATCH_NO_SHARED_CONTRACTS

Explanation: This error code indicates indicates a special case of a fork, where a counter-participant sent a commitment for a period, while this participant does not think that there are any shared active contracts at the end of that period. This case can occur due to malicious behavior of the counter-participant, bugs, or if the administrator of the counter-participant node manually changed contracts using repair and created an ACS state incompatible with other participants. The counter-participant will log an ACS_COMMITMENT_MISMATCH.
Resolution: Please consult the runbook on inspecting commitment mismatches in order to check the cause of the mismatch. Either repair the store of this participant or of the counter participant.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

3.1.2. DegradationError

ACS_COMMITMENT_DEGRADATION

Explanation: This error code indicates that the participant node is behind some of its counter-participants in commitment computation, perhaps due to heavy load, and enters catch-up mode. This is referred to as a degradation. The danger of a degraded participant is that its counter-participants might blacklist it in order to unblock their pruning, therefore those counter-participants would not wait for the participant’s commitments, which weakens the non-repudiation guarantees. An operator can configure the threshold of how many reconciliation intervals the participant needs to fall behind for catch-up mode to trigger, as well as the number of reconciliation intervals that the participant skips in catch-up mode. However, any counter-participant operator can unilaterally decide to blacklist a participant based on their own tolerance to slow participants, regardless of each participant’s configured parameters.
Resolution: Catch-up mode is enabled and the participant should recover on its own.
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

ACS_COMMITMENT_DEGRADATION_WITH_INEFFECTIVE_CONFIG

Explanation: This error code indicates that there is a degradation in commitment computation and the catch-up mode started, however the catch-up mode configuration is invalid and will not improve performance. This is because the configuration for the catch-up mode has a skip step of 1, which means that the participant will not skip any commitment computation. The participant runs the risk of remaining degraded, and its counter-participants might blacklist it and not actively wait for commitments, weakening the non-repudiation guarantees.
Resolution: Please update catch-up mode configuration to have a catchUpIntervalSkip higher than 1
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

3.2. AddPartyError

ADD_PARTY_DISCONNECTED_FROM_SYNCHRONIZER

Explanation: This error indicates that adding a party with active contracts to a participant and a synchronizer has been interrupted by a participant having disconnected from a synchronizer.
Resolution: Reconnect the participant to the synchronizer to unblock adding the party.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

ADD_PARTY_OTHER

Explanation: This error is currently used as a catch-all for a variety of failures that prevent adding a party to a participant and synchronizer.
Resolution: Inspect the message, potentially rebuild the target participant, and retry adding the party.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

3.3. LedgerApiErrorGroup

3.3.1. CommandExecutionErrors

DISCLOSED_CONTRACTS_SYNCHRONIZER_ID_MISMATCH

Explanation: This error occurs if some of the disclosed contracts attached to the command submission that were also used in command interpretation have specified mismatching synchronizer ids. This can happen if the synchronizer ids of the disclosed contracts are out of sync OR if the originating contracts are assigned to different synchronizers.
Resolution: Retry the submission with an up-to-date set of attached disclosed contracts or re-create a command submission that only uses disclosed contracts residing on the same synchronizer.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status ABORTED including a detailed error message.

FAILED_TO_EXECUTE_TRANSACTION

Explanation: This error occurs if the participant fails to execute a transaction via the interactive submission service.
Resolution: Inspect error details and report the error.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

FAILED_TO_PREPARE_TRANSACTION

Explanation: This error occurs if the participant fails to prepare a transaction via the interactive submission service.
Resolution: Inspect error details and report the error.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INTERPRETATION_TIME_EXCEEDED

Explanation: This error occurs when the interpretation of a command exceeded the time limit, defined as the maximum time that can be assigned by the ledger when it starts processing the command. It corresponds to the time assigned upon submission by the participant (the ledger time) + a tolerance defined by the ledgerTimeToRecordTimeTolerance ledger configuration parameter. Reasons for exceeding this limit can vary: the participant may be under high load, the command interpretation may be very complex, or even run into an infinite loop due to a mistake in the Daml code.
Resolution: Due to the halting problem, we cannot determine whether the interpretation will eventually complete. As a developer: inspect your code for possible non-terminating loops or consider reducing its complexity. As an operator: check and possibly update the resources allocated to the system, as well as the time-related configuration parameters (see “Time on Daml Ledgers” in the “Daml Ledger Model Concepts” doc section and the set_ledger_time_record_time_tolerance console command).
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

PACKAGE_NAME_DISCARDED_DUE_TO_UNVETTED_PACKAGES

Explanation: A package-name required in command interpretation was discarded in topology-aware package selection due to vetting topology restrictions.
Resolution: Revisit the command submission and ensure it conforms with the vetted topology state of the submitters and informees.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

PACKAGE_SELECTION_FAILED

Explanation: This error occurs when topology-aware package selection could not yield a valid candidate set of vetted packages needed for command submission.
Resolution: Inspect the error message and adjust the topology state or the submitted command
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PRESCRIBED_SYNCHRONIZER_ID_MISMATCH

Explanation: This error occurs when the synchronizer id provided in the command submission mismatches the synchronizer id specified in one of the disclosed contracts used in command interpretation.
Resolution: Retry the submission with all disclosed contracts residing on the target submission synchronizer.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

3.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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

3.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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

3.3.1.3. Interpreter

CONTRACT_DOES_NOT_IMPLEMENT_INTERFACE

Explanation: This error occurs when you try to coerce/use a contract via an interface that it does not implement.
Resolution: Ensure the contract you are calling does implement the interface you are using to do so. Avoid writing LF/low-level interface implementation classes manually.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

CONTRACT_DOES_NOT_IMPLEMENT_REQUIRING_INTERFACE

Explanation: This error occurs when you try to create/use a contract that does not implement the requiring interfaces of some other interface that it does implement.
Resolution: Ensure you implement all required interfaces correctly, and avoid writing LF/low-level interface implementation classes manually.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

CONTRACT_HASHING_ERROR

Explanation: This error occurs when trying to hash an ill-formed contract.
Resolution: Ensure that the contract being hashed is a valid contract.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

CONTRACT_ID_COMPARABILITY

Explanation: This error occurs when you attempt to compare a global and local contract ID of the same discriminator.
Resolution: Avoid constructing contract IDs manually.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

CONTRACT_ID_IN_CONTRACT_KEY

Explanation: This error occurs when a contract key contains a contract ID, which is illegal for hashing reasons.
Resolution: Ensure your contracts key field cannot contain a contract ID.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

CREATE_EMPTY_CONTRACT_KEY_MAINTAINERS

Explanation: This error occurs when you try to create a contract that has a key, but with empty maintainers.
Resolution: Check the definition of the contract key’s maintainers, and ensure this list won’t be empty given your creation arguments.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

DAML_FAILURE

Explanation: This error is thrown by use of failWithStatus in daml code. The Daml code determines the canton error category, and thus the grpc status code.
Resolution: Ensure that you are using the contract correctly, and that the choice implementation does not have a bug.
Category: <determined by daml code>
Conveyance: Conveyance is determined by the category, which is selected in daml code. Refer to the documentation of the actual error category encoded in the raised error for details.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

DISCLOSED_CONTRACT_KEY_HASHING_ERROR

Explanation: This error occurs if a user attempts to provide a key hash for a disclosed contract which we have already cached to be different.
Resolution: Ensure the contract ID and contract payload you have provided in your disclosed contract is correct.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

FETCH_EMPTY_CONTRACT_KEY_MAINTAINERS

Explanation: This error occurs when you try to fetch a contract by key, but that key would have empty maintainers.
Resolution: Check the definition of the contract key’s maintainers, and ensure this list won’t be empty given the contract key you are fetching.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INTERPRETATION_DEV_ERROR

Explanation: This error is a catch-all for errors thrown by in-development features, and should never be thrown in production.
Resolution: See the error message for details of the specific in-development feature error. If this is production, avoid using development features.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

INTERPRETATION_USER_ERROR

Explanation: This error occurs when a user calls abort or error on an LF version before native exceptions were introduced.
Resolution: Either remove the call to abort, error or perhaps assert, or ensure you are exercising your contract choice as the author expects.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

MALFORMED_TEXT

Explanation: This error occurs when a Daml text is not a valid UTF-8 string or contains null characters.
Resolution: Restructure your code and reduce value nesting.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

NON_COMPARABLE_VALUES

Explanation: This error occurs when you attempt to compare two values of different types using the built-in comparison types.
Resolution: Avoid using the low level comparison build, and instead use the Eq class.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TEMPLATE_PRECONDITION_VIOLATED

Explanation: This error occurs when a contract’s pre-condition (the ensure clause) is violated on contract creation.
Resolution: Ensure the contract argument you are passing into your create doesn’t violate the conditions of the contract.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

UNHANDLED_EXCEPTION

Explanation: This error occurs when a user throws an error and does not catch it with try-catch.
Resolution: Either your error handling in a choice body is insufficient, or you are using a contract incorrectly.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

VALUE_NESTING

Explanation: This error occurs when you nest values too deeply.
Resolution: Restructure your code and reduce value nesting.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

WRONGLY_TYPED_CONTRACT

Explanation: This error occurs when you try to fetch/use a contract in some way with a contract ID that doesn’t match the template type on the ledger.
Resolution: Ensure the contract IDs you are using are of the type we expect on the ledger. Avoid unsafely coercing contract IDs.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

UNRESOLVED_PACKAGE_NAME

Explanation: This error occurs if the Daml engine interpreter cannot resolve a package name to any vetted package. This can be caused by a commmand using an explicit disclosure produced by a package that hasn’t been vetted yet by the participant or by a command that uses a contract whose creation package has been force-unvetted.
Resolution: Ensure the command doesn’t use a package that has not been yet vetted or has been unvetted.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.1.3.2. CryptoError

INTERPRETATION_CRYPTO_ERROR_MALFORMED_BYTE_ENCODING

Explanation: Hex string is malformed
Resolution: Ensure string is non-empty, of even length and only contains hex characters (i.e. matches [0-9a-fA-F]+)
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

INTERPRETATION_CRYPTO_ERROR_MALFORMED_KEY

Explanation: Public key hex encoding is malformed
Resolution: Ensure public key is a DER encoded Secp256k1 public key
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

INTERPRETATION_CRYPTO_ERROR_MALFORMED_SIGNATURE

Explanation: Signature hex encoding is malformed
Resolution: Ensure signature is a DER encoded Keccak256 digest
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.3.1.3.3. UpgradeError

INTERPRETATION_UPGRADE_ERROR_AUTHENTICATION_FAILED

Explanation: Cannot authenticate contract
Resolution: Verify that the template used for loading the contract is upgrade-compatible with the template that created it.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INTERPRETATION_UPGRADE_ERROR_TRANSLATION_FAILED

Explanation: Contract is malformed or doesn’t match the expected type
Resolution: Verify that the template used for loading the contract is upgrade-compatible with the template that created it.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INTERPRETATION_UPGRADE_ERROR_VALIDATION_FAILED

Explanation: Validation fails when trying to upgrade the contract
Resolution: Verify that neither the signatories, nor the observers, nor the contract key, nor the key’s maintainers, nor the package name have changed
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

3.3.2. AdminServicesErrorGroup

3.3.2.1. PartyManagementServiceErrors

CONCURRENT_PARTY_DETAILS_UPDATE_DETECTED

Explanation: Concurrent updates to a party can be controlled by supplying an update request with a resource version (this is optional). A party’s resource version can be obtained by reading the party on the Ledger API. There was attempt to update a party using a stale resource version, indicating that a different process had updated the party earlier.
Resolution: Read this party again to obtain its most recent state and in particular its most recent resource version. Use the obtained information to build and send a new update request.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

INTERNAL_PARTY_RECORD_ALREADY_EXISTS

Explanation: Each on-ledger party known to this participant node can have a participant’s local metadata assigned to it. The local information about a party referred to by this request was found when it should have been not found.
Resolution: This error can indicate a problem with the server’s storage or implementation.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

INTERNAL_PARTY_RECORD_NOT_FOUND

Explanation: Each on-ledger party known to this participant node can have a participant’s local metadata assigned to it. The local information about a party referred to by this request was not found when it should have been found.
Resolution: This error can indicate a problem with the server’s storage or implementation.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

INVALID_PARTY_DETAILS_UPDATE_REQUEST

Explanation: There was an attempt to update a party using an invalid update request.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

MAX_PARTY_DETAILS_ANNOTATIONS_SIZE_EXCEEDED

Explanation: A party can have at most 256kb worth of annotations in total measured in number of bytes in UTF-8 encoding. There was an attempt to allocate or update a party such that this limit would have been exceeded.
Resolution: Retry with fewer annotations or delete some of the party’s existing annotations.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PARTY_NOT_FOUND

Explanation: The party referred to by the request was not found.
Resolution: Check that you are connecting to the right participant node and that the party is spelled correctly.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.2.2. UserManagementServiceErrors

CONCURRENT_USER_UPDATE_DETECTED

Explanation: Concurrent updates to a user can be controlled by supplying an update request with a resource version (this is optional). A user’s resource version can be obtained by reading the user on the Ledger API. There was attempt to update a user using a stale resource version, indicating that a different process had updated the user earlier.
Resolution: Read this user again to obtain its most recent state and in particular its most recent resource version. Use the obtained information to build and send a new update request.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

INVALID_USER_UPDATE_REQUEST

Explanation: There was an attempt to update a user using an invalid update request.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

MAX_USER_ANNOTATIONS_SIZE_EXCEEDED

Explanation: A user can have at most 256kb worth of annotations in total measured in number of bytes in UTF-8 encoding. There was an attempt to create or update a user such that this limit would have been exceeded.
Resolution: Retry with fewer annotations or delete some of the user’s existing annotations.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOO_MANY_USER_RIGHTS

Explanation: A user can have only a limited number of user rights. There was an attempt to create a user with too many rights or grant too many rights to a user.
Resolution: Retry with a smaller number of rights or delete some of the already existing rights of this user. Contact the participant operator if the limit is too low.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

USER_DELETED_WHILE_UPDATING

Explanation: There was attempt to update a user while a different process deleted the user at the same time.
Resolution: Read all users again and reattempt the operation with another user.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

USER_NOT_FOUND

Explanation: The user / idp combination 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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.2.3. IdentityProviderConfigServiceErrors

IDP_CONFIG_ALREADY_EXISTS

Explanation: There already exists an identity provider configuration with the same identity provider id.
Resolution: Check that you are connecting to the right participant node and the identity provider id is spelled correctly, or use an identity provider that already exists.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

IDP_CONFIG_BY_ISSUER_NOT_FOUND

Explanation: The identity provider config referred to by the request was not found.
Resolution: Check that you are connecting to the right participant node and the identity provider config is spelled correctly, or create the configuration.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

IDP_CONFIG_ISSUER_ALREADY_EXISTS

Explanation: There already exists an identity provider configuration with the same issuer.
Resolution: Check that you are connecting to the right participant node and the identity provider id is spelled correctly, or use an identity provider that already exists.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

IDP_CONFIG_NOT_FOUND

Explanation: The identity provider config referred to by the request was not found.
Resolution: Check that you are connecting to the right participant node and the identity provider config is spelled correctly, or create the configuration.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

INVALID_IDENTITY_PROVIDER_UPDATE_REQUEST

Explanation: There was an attempt to update an identity provider config using an invalid update request.
Resolution: Inspect the error details for specific information on what made the request invalid. Retry with an adjusted update request.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOO_MANY_IDENTITY_PROVIDER_CONFIGS

Explanation: A system can have only a limited number of identity provider configurations. There was an attempt to create an identity provider configuration.
Resolution: Delete some of the already existing identity provider configurations. Contact the participant operator if the limit is too low.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.3.3. AdminServiceErrors

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

INTERNALLY_INVALID_KEY

Explanation: A cryptographic key used by the configured system is not valid
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.3.4. RequestValidationErrors

DISCLOSED_CONTRACTS_CONFLICTING_PAYLOADS

Explanation: This error is emitted when a submitted ledger API command contains disclosed contracts with conflicting payloads for the same contract ID.
Resolution: This may be considered a security incident or a defect on the server. Please contact support or the providers of the disclosed contract payloads.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

LEDGER_TIME_OUTSIDE_BOUNDS

Explanation: This error is emitted when an attempt is made to submit a transaction with at a time that is outside the ledger time bounds required by the transaction.
Resolution: If the time bounds are in the future then retry within the time bounds, if in the past a new transaction needs to be prepared with a current or future time
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

NEGATIVE_OFFSET

Explanation: The supplied offset is a negative integer.
Resolution: Ensure the offset specified is a negative integer.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

NON_POSITIVE_OFFSET

Explanation: The supplied offset is not a positive integer.
Resolution: Ensure the offset specified is a positive (non zero) integer.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status OUT_OF_RANGE including a detailed error message.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PARTICIPANT_DATA_ACCESSED_AFTER_LEDGER_END

Explanation: This rejection is given when a read request tries to access data after the ledger end
Resolution: Use an offset that is before the ledger end.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNKNOWN_RESOURCE

Explanation: This error is emitted when a submitted ledger API command refers to a non-existing resource.
Resolution: Inspect the reason given and correct your application.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.4.1. NotFound

CONTRACT_EVENTS_NOT_FOUND

Explanation: Events for the specified contract ID do not exist or the event format specified filters them out.
Resolution: Check the contract ID and verify that the requested events are not being filtered out by the event format.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

NO_INTERFACE_FOR_PACKAGE_NAME_AND_QUALIFIED_NAME

Explanation: The queried type reference for the specified package name and interface qualified-name does not reference any interface uploaded on this participant
Resolution: Use a interface qualified-name referencing already uploaded interface-ids or ask the participant operator to upload the necessary packages.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

NO_TEMPLATES_FOR_PACKAGE_NAME_AND_QUALIFIED_NAME

Explanation: The queried type reference for the specified package name and template qualified-name does not reference any template uploaded on this participant
Resolution: Use a template qualified-name referencing already uploaded template-ids or ask the participant operator to upload the necessary packages.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

PACKAGE_NAMES_NOT_FOUND

Explanation: The queried package names do not match packages uploaded on this participant.
Resolution: Use valid package names or ask the participant operator to upload the necessary packages.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TEMPLATES_OR_INTERFACES_NOT_FOUND

Explanation: The queried template or interface ids do not exist.
Resolution: Use valid template or interface ids in your query or ask the participant operator to upload the package containing the necessary interfaces/templates.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

UPDATE_NOT_FOUND

Explanation: The update does not exist or the update format specified filters it out.
Resolution: Check the update id or offset and verify that the requested update is not being filtered out by the update format.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.5. 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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

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 and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

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 and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SUBMISSION_ALREADY_IN_FLIGHT

Explanation: Another command submission with the same change ID (user 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 and exposed on the API with grpc-status ABORTED including a detailed error message.

3.3.6. PackageServiceErrors

DAR_DEPENDENCIES_NOT_VALID

Explanation: This error indicates that the uploaded Dar is broken because it is missing internal dependencies or has unused internal dependencies.
Resolution: Contact the supplier of the Dar.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

3.3.6.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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

MAIN_PACKAGE_IN_DAR_DOES_NOT_MATCH_EXPECTED

Explanation: The main package of the uploaded DAR does not match the expected package id.
Resolution: Investigate where the DAR is coming from and whether it was manipulated or the provided package id was wrong.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

3.3.7. SyncServiceRejectionErrors

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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

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. It is exposed on the API with grpc-status PERMISSION_DENIED without any details for security reasons.

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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.3.7.1. Internal

INTERNALLY_DUPLICATE_KEYS

Explanation: The participant didn’t detect an attempt by the transaction submission to use the same key for two active contracts.
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

INTERNALLY_INCONSISTENT_KEYS

Explanation: The participant didn’t detect an inconsistent key usage in the transaction. Within the transaction, an exercise, fetch or lookupByKey failed because the mapping of key -> contract ID was inconsistent with earlier actions.
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

3.3.8. JsonApiErrors

JSON_API_MAXIMUM_LIST_ELEMENTS_NUMBER_REACHED

Explanation: This happens when the number of returned elements is equal or greater to the node limit. The limit is defined by the node configuration and can be changed by the operator. Check ‘canton.participants.<participant-id>.http-ledger-api.websocket-config.http-list-max-elements-limit’. Notice: If configured in the participant node config, the actual returned number is the minimum between the “limit” query parameter in the request and this one . If the request query “limit” is the same as the mentioned configuration, it allows to return result set up to server limit without producing error.
Resolution: 1. Preferred solution is to use websocket endpoint to get results in chunks. 2. It is possible to increase the limit by changing the node configuration ‘http-list-max-elements-limit’ but this may have a severe impact on a node performance.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

JSON_API_PACKAGE_SELECTION_FAILED

Explanation: This error occurs when the Ledger JSON API server fails to find a suitable set of package-ids for decoding a given set of commands in a request.
Resolution: Inspect the error message and ensure that: 1. The requested packages are uploaded on the participant node. 2. The topology state satisfies the required vetting for the interested parties
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.4. CantonPackageServiceError

PACKAGE_OR_DAR_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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PACKAGE_SERVICE_CANNOT_AUTODETECT_SYNCHRONIZER

Resolution: If the node is not connected to any synchronizer, connect to a synchornizer first. If the participant is connected to more than one synchronizer, explicitly specify the synchronizer id.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PACKAGE_SERVICE_NOT_CONNECTED_TO_SYNCHRONIZER

Resolution: Connect to a synchronzer before vetting a package.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.4.1. Vetting

AMBIGUOUS_VETTING_REFERENCE

Explanation: The vetted package reference matches more than one package in the package store.
Resolution: Check the provided vetted package reference and re-try the operation.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNRESOLVED_VETTING_REFERENCE

Explanation: The vetted package reference does not match any package in the package store.
Resolution: Check the provided vetted package reference and re-try the operation.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.4.2. Fetching

DAR_NOT_FOUND

Explanation: The id specified in the request does not match the main package-id of a DAR stored on the participant.
Resolution: Check the provided package ID and re-try the operation.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

PACKAGE_CONTENT_NOT_FOUND

Explanation: This error indicates that the requested package does not exist in the package store.
Resolution: Provide an existing package id
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.5. TransactionErrorGroup

3.5.1. LocalRejectError

3.5.1.1. AssignmentRejects

ASSIGNMENT_ALREADY_COMPLETED

Explanation: This rejection is emitted by a participant if an assignment has already been completed.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

LOCAL_VERDICT_ACTIVATES_EXISTING_CONTRACTS

Explanation: This error indicates that the assignment would activate already existing contracts.
Resolution: This error indicates either faulty or malicious behaviour.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

3.5.1.2. ReassignmentRejects

INCONSISTENT_REASSIGNMENT_ID

Explanation: Validation checks failed for reassignment id.
Resolution: This indicates a malicious or faulty behaviour.
Category: UnredactedSecurityAlert
Conveyance: This error is logged with log-level ERROR on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

REASSIGNMENT_VALIDATION_FAILED

Explanation: Validation checks failed for reassignments.
Resolution: This indicates a race condition due to a in-flight topology change, or malicious or faulty behaviour.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.5.1.3. 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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for 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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

LOCAL_VERDICT_MALFORMED_REQUEST

Explanation: This rejection is made by a participant if a request is malformed.
Resolution: Please contact support.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

3.5.1.4. ConsistencyRejections

LOCAL_VERDICT_INACTIVE_CONTRACTS

Explanation: The transaction is referring to contracts that have either been previously archived, reassigned to another synchronizer, 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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

LOCAL_VERDICT_LOCKED_CONTRACTS

Explanation: The transaction is referring to locked contracts which are in the process of being created, reassigned, 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 and exposed on the API with grpc-status ABORTED including a detailed error message.

3.5.1.5. 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 or adjust the dynamic synchronizer parameter ledgerTimeRecordTimeTolerance (and possibly the participant and mediator reaction timeout). For short-running transactions, simply retry.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

LOCAL_VERDICT_PREPARATION_TIME_OUT_OF_BOUND

Explanation: This error is thrown if the preparation 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 and 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: In the first instance, resubmit your transaction. If the rejection still appears spuriously, consider increasing the confirmationResponseTimeout or mediatorReactionTimeout values in the DynamicSynchronizerParameters. If the rejection appears unrelated to timeout settings, validate that the sequencer and mediator function correctly.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

3.5.1.6. UnassignmentRejects

UNASSIGNMENT_ACTIVENESS_CHECK_FAILED

Explanation: Activeness check failed for unassignment submission. This rejection occurs if the contract to be reassigned has already been reassigned or is currently locked (due to a competing transaction) on synchronizer.
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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.5.2. TransactionRoutingError

AUTOMATIC_REASSIGNMENT_FOR_TRANSACTION_FAILED

Explanation: This error indicates that the automated reassignment could not succeed, as the current topology does not allow the reassignment 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 and 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 synchronizer router.
Resolution: Please contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

UNABLE_TO_GET_STATIC_PARAMETERS

Explanation: This error indicates that static parameters information could not be queried.
Resolution: Check that the participant is connected to the synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNABLE_TO_GET_TOPOLOGY_SNAPSHOT

Explanation: This error indicates that topology information could not be queried.
Resolution: Check that the participant is connected to the synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.5.2.1. MalformedInputErrors

DISCLOSED_CONTRACT_AUTHENTICATION_FAILED

Explanation: A provided disclosed contract could not be authenticated against the provided contract id.
Resolution: Ensure that disclosed contracts provided with command submission match the original contract creation content as sourced from the Ledger API. If the problem persists, contact the participant operator.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INVALID_DISCLOSED_CONTRACT

Explanation: A provided disclosed contract could not be processed.
Resolution: Ensure that disclosed contracts provided with command submission have an authenticated contract id (i.e. have been created in participant nodes running Canton protocol version 4 or higher) and match the original contract creation format and content as sourced from the Ledger API. If the problem persists, contact the participant operator.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INVALID_PARTY_IDENTIFIER

Explanation: The given party identifier is not a valid Canton party identifier.
Resolution: Ensure that your commands only refer to correct and valid Canton party identifiers of parties that are properly enabled on the system
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INVALID_READER

Explanation: The party defined as a reader (actAs or readAs) 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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

3.5.2.2. TopologyErrors

INFORMEES_NOT_ACTIVE

Explanation: This error indicates that the informees are known, but there is no connected synchronizer on which all the informees are hosted.
Resolution: Ensure that there is such a synchronizer, as Canton requires a synchronizer where all informees are present.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NOT_CONNECTED_TO_ALL_CONTRACT_SYNCHRONIZERS

Explanation: This error indicates that the transaction is referring to contracts on synchronizers to which this participant is currently not connected.
Resolution: Check the status of your synchronizer connections.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NO_COMMON_SYNCHRONIZER

Explanation: This error indicates that there is no common synchronizer to which all submitters can submit and all informees are connected.
Resolution: Check that your participant node is connected to all synchronizers you expect and check that the parties are hosted on these synchronizers as you expect them to be.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NO_SYNCHRONIZER_FOR_SUBMISSION

Explanation: This error indicates that no valid synchronizer was found for submission.
Resolution: Check the status of your synchronizer connections, that packages are vetted and that you are connected to synchronizers running recent protocol versions.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NO_SYNCHRONIZER_ON_WHICH_ALL_SUBMITTERS_CAN_SUBMIT

Explanation: This error indicates that a transaction has been sent where the system can not find any active ” + “synchronizer on which this participant can submit in the name of the given set of submitters.
Resolution: Ensure that you are connected to a synchronizer where this participant has submission rights. Check that you are actually connected to the synchronizers 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 and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

SUBMITTERS_NOT_ACTIVE

Explanation: This error indicates that the submitters are known, but there is no connected synchronizer on which all the submitters are hosted.
Resolution: Ensure that there is such a synchronizer, as Canton requires a synchronizer where all submitters are present.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SUBMITTER_ALWAYS_STAKEHOLDER

Explanation: This error indicates that the transaction requires contract reassignments for which the submitter must be a stakeholder.
Resolution: Check that your participant node is connected to all synchronizers you expect and check that the parties are hosted on these synchronizers as you expect them to be.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNKNOWN_CONTRACT_SYNCHRONIZERS

Explanation: This error indicates that the transaction is referring to contracts whose synchronizer is not currently known.
Resolution: Ensure all reassignment operations on contracts used by the transaction have completed and check connectivity to synchronizers.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNKNOWN_INFORMEES

Explanation: This error indicates that the transaction is referring to some informees that are not known on any connected synchronizer.
Resolution: Check the list of submitted informees and check if your participant is connected to the synchronizers you are expecting it to be.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

UNKNOWN_SUBMITTERS

Explanation: This error indicates that the transaction is referring to some submitters that are not known on any connected synchronizer.
Resolution: Check the list of provided submitters and check if your participant is connected to the synchronizers you are expecting it to be.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.5.2.3. ConfigurationErrors

INVALID_PRESCRIBED_SYNCHRONIZER_ID

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

SUBMISSION_SYNCHRONIZER_NOT_READY

Explanation: This error indicates that the transaction should be submitted to a synchronizer which is not connected or not configured.
Resolution: Ensure that the synchronizer specified in the workflowId is correctly connected.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.5.3. LocalAbstainError

CANNOT_PERFORM_ALL_VALIDATIONS

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

3.5.4. 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 and exposed on the API with grpc-status ABORTED including a detailed error message.

CONTRACT_AUTHENTICATION_FAILED

Explanation: At least one of the transaction’s input contracts could not be authenticated.
Resolution: Retry the submission with correctly authenticated contracts.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

INVALID_EXTERNAL_SIGNATURE

Explanation: This error occurs when a transaction with external signatures is submitted, but the signature is invalid. This can be caused either by an incorrect hash computation, or by an invalid signing key.
Resolution: Check that the hashing function used is correct and that the signing key is correctly registered for the submitting party.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INVALID_EXTERNAL_TRANSACTION

Explanation: This error occurs when an invalid transaction with external signatures is submitted, for which a valid hash cannot be computed.
Resolution: Inspect the error message and re-submit a valid transaction instead.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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. Alternatively, you can increase the dynamic synchronizer parameter ledgerTimeRecordTimeTolerance.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

NO_VIEW_WITH_VALID_RECIPIENTS

Explanation: This error occurs when the transaction does not contain a valid set of recipients.
Resolution: It is possible that a concurrent change in the relationships between parties and participants occurred during request submission. Resubmit the request.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

PACKAGE_NOT_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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PARTICIPANT_OVERLOADED

Explanation: The participant has rejected all incoming commands during a configurable grace period.
Resolution: Configure more restrictive resource limits (enterprise only). Change applications to submit commands at a lower rate. Configure a higher value for myParticipant.parameters.warnIfOverloadedFor.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

SEQUENCER_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 INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

SEQUENCER_REQUEST_FAILED

Explanation: This error occurs when the command cannot be sent to the synchronizer.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

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 and exposed on the API with grpc-status ABORTED including a detailed error message.

SUBMISSION_INTERNAL_ERROR

Explanation: An internal error occurred during transaction submission.
Resolution: Please contact support and provide the failure reason.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

SYNCHRONIZER_WITHOUT_MEDIATOR

Explanation: The participant routed the transaction to a synchronizer without an active mediator.
Resolution: Add a mediator to the synchronizer.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

UNKNOWN_CONTRACT_SYNCHRONIZER

Explanation: This error occurs if a transaction was submitted referring to a contract that is not known on the synchronizer. This can occur in case of race conditions between a transaction and an archival or unassignment.
Resolution: Check synchronizer for submission and/or re-submit the transaction.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.5.5. 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

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 and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

NOT_CONNECTED_TO_ANY_SYNCHRONIZER

Explanation: This error results when specific requests are submitted to a participant that is not connected to any synchronizer.
Resolution: Connect your participant to a synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NOT_CONNECTED_TO_SYNCHRONIZER

Explanation: This errors results if a command is submitted to a participant that is not connected to a synchronizer needed to process the command.
Resolution: Connect your participant to the required synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.6. SyncServiceError

INVALID_ARGUMENT_SYNC_SERVICE

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

PARTY_ALLOCATION_CANNOT_DETERMINE_SYNCHRONIZER

Explanation: The participant is connected to more than one synchronizer and can therefore not automatically detect on which synchronizer the party should be allocated.
Resolution: Explicitly specify the synchronizer on which to allocate the party or disconnect from all but one synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PARTY_ALLOCATION_WITHOUT_CONNECTED_SYNCHRONIZER

Explanation: The participant is not connected to a synchronizer and can therefore not allocate a party because the party notification is configured as party-notification.type = via-synchronizer.
Resolution: Connect the participant to a synchronizer first or change the participant’s party notification config to eager.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_REGISTRATION

Explanation: This error results on an attempt to register a new synchronizer.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

SYNC_SERVICE_ALARM

Explanation: The participant has detected that another node is behaving maliciously.
Resolution: Contact support.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

SYNC_SERVICE_ALIAS_RESOLUTION

Explanation: This error results if the service cannot infer the active synchronizer for the alias.
Resolution: Please confirm the synchronizer alias is correct, or configure the synchronizer before (re)connecting.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

SYNC_SERVICE_BAD_CONNECTIVITY

Explanation: This error is reported in case of validation failures when attempting to register new or change existing sequencer connections. This can be caused by unreachable nodes, a bad TLS configuration, or in case of a mismatch of synchronizer ids reported by the sequencers or mismatched sequencer-ids within a sequencer group.
Resolution: Check that the connection settings provided are correct. If they are but correspond to temporarily inactive sequencers, you may also turn off the validation.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_BECAME_PASSIVE

Explanation: This error is logged when a connected synchronizer is disconnected because the participant became passive.
Resolution: Fail over to the active participant replica.
Category: TransientServerFailure
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

SYNC_SERVICE_PASSIVE_REPLICA

Explanation: This error results if a admin command is submitted to the passive replica.
Resolution: Send the admin command to the active replica.
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

SYNC_SERVICE_PHYSICAL_ID_REGISTRATION

Explanation: This error results if the service cannot register the physical synchronizer id for the given alias.
Resolution: Please confirm the synchronizer alias and id are correct.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

SYNC_SERVICE_STARTUP_ERROR

Explanation: This error indicates a synchronizer failed to start or initialize properly.
Resolution: Please check the underlying error(s) and retry if possible. If not, contact support and provide the failure reason.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_SYNCHRONIZERS_MUST_BE_OFFLINE

Explanation: This error is emitted when an operation is attempted such as repair that requires the synchronizers to be disconnected and clean.
Resolution: Disconnect the still connected synchronizers before attempting the command.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_SYNCHRONIZER_DISABLED_US

Explanation: This error is logged when the synchronization service shuts down because the remote sequencer API is denying access.
Resolution: Contact the sequencer operator and inquire why you are not allowed to connect anymore.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_SYNCHRONIZER_DISCONNECTED

Explanation: This error is logged when a connected synchronizer 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

SYNC_SERVICE_SYNCHRONIZER_MUST_NOT_HAVE_IN_FLIGHT_TRANSACTIONS

Explanation: This error is emitted when a synchronizer migration is attempted while transactions are still in-flight on the source synchronizer.
Resolution: Ensure the source synchronizer has no in-flight transactions by reconnecting participants to the source synchronizer, halting activity on the participants and waiting for in-flight transactions to complete or time out. Afterwards invoke migrate_synchronizer again. As a last resort, you may force the synchronizer migration ignoring in-flight transactions using the force flag on the command. Be advised, forcing a migration may lead to a ledger fork.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_SYNCHRONIZER_STATUS_NOT_ACTIVE

Explanation: This error is logged when a synchronizer has a non-active status.
Resolution: If you attempt to connect to a synchronizer that has either been migrated off or has a pending migration, this error will be emitted. Please complete the migration before attempting to connect to it.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNC_SERVICE_UNKNOWN_SYNCHRONIZER

Explanation: This error results if a synchronizer connectivity command is referring to a synchronizer alias that has not been registered.
Resolution: Please confirm the synchronizer alias is correct, or configure the synchronizer before (re)connecting.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.6.1. SynchronizerMigrationError

BROKEN_SYNCHRONIZER_MIGRATION

Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

INVALID_SYNCHRONIZER_MIGRATION_REQUEST

Explanation: This error results when invalid arguments are passed to the migration command.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.6.2. SynchronizerRegistryError

INITIAL_ONBOARDING_ERROR

Explanation: This error indicates that there has been an initial onboarding problem.
Resolution: Check the underlying cause and retry if possible. If not, contact support and provide the failure reason.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

TOPOLOGY_CONVERSION_ERROR

Explanation: This error indicates that there was an error converting topology transactions during connecting to a synchronizer.
Resolution: Contact the operator of the topology management for this node.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

3.6.2.1. ConfigurationErrors

CANNOT_ISSUE_SYNCHRONIZER_TRUST_CERTIFICATE

Explanation: This error indicates that the participant can not issue a synchronizer trust certificate. Such a certificate is necessary to become active on a synchronizer. Therefore, it must be present in the authorized store of the participant topology manager.
Resolution: Manually upload a valid synchronizer trust certificate for the given synchronizer 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

MISCONFIGURED_STATIC_SYNCHRONIZER_PARAMETERS

Explanation: This error indicates that the participant is configured to connect to multiple sequencers of a synchronizer but their static synchronizer parameters are different from other sequencers.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCERS_FROM_DIFFERENT_SYNCHRONIZERS_ARE_CONFIGURED

Explanation: This error indicates that the participant is configured to connect to multiple synchronizer sequencers from different synchronizers.
Resolution: Carefully verify the connection settings.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_PARAMETERS_CHANGED

Explanation: Error indicating that the synchronizer parameters have been changed, while this isn’t supported yet.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.6.2.2. ConnectionErrors

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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

FAILED_TO_CONNECT_TO_SEQUENCERS

Explanation: This error indicates that the participant failed to connect to the sequencers.
Resolution: Inspect the provided reason.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and 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 and 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 synchronizer operator. If the participant was previously successfully connected to the synchronizer, then this error indicates that the synchronizer operator has deactivated the participant.
Resolution: Contact the synchronizer operator and inquire the permissions your participant node has on the given synchronizer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_IS_NOT_AVAILABLE

Explanation: This error results if the GRPC connection to the synchronizer service fails with GRPC status UNAVAILABLE.
Resolution: Check your connection settings and ensure that the synchronizer can really be reached.
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

3.6.2.3. HandshakeErrors

SYNCHRONIZER_ALIAS_DUPLICATION

Explanation: This error indicates that the synchronizer alias was previously used to connect to a synchronizer with a different synchronizer id. This is a known situation when an existing participant is trying to connect to a freshly re-initialised synchronizer.
Resolution: Carefully verify the connection settings.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_CRYPTO_HANDSHAKE_FAILED

Explanation: This error indicates that the synchronizer 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_HANDSHAKE_FAILED

Explanation: This error indicates that the participant to synchronizer 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SYNCHRONIZER_ID_MISMATCH

Explanation: This error indicates that the synchronizer id does not match the one that the participant expects. If this error happens on a first connect, then the synchronizer id defined in the synchronizer connection settings does not match the remote synchronizer. If this happens on a reconnect, then the remote synchronizer 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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

3.8. RepairServiceError

CONTRACT_ASSIGNATION_CHANGE_ERROR

Explanation: The assignation of a contract cannot be changed due to an error.
Resolution: Retry after operator intervention.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

CONTRACT_PURGE_ERROR

Explanation: A contract cannot be purged due to an error.
Resolution: Retry after operator intervention.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

CONTRACT_SERIALIZATION_ERROR

Explanation: A contract cannot be serialized due to an error.
Resolution: Retry after operator intervention.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

IMPORT_ACS_ERROR

Explanation: Import ACS has failed.
Resolution: Retry after operator intervention.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

INCONSISTENT_ACS_SNAPSHOT

Explanation: The ACS snapshot cannot be returned because it contains inconsistencies. This is likely due to the request happening concurrently with pruning.
Resolution: Retry the operation
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

INVALID_ACS_SNAPSHOT_TIMESTAMP

Explanation: The participant does not support serving an ACS snapshot at the requested timestamp, likely because some concurrent processing has not yet finished.
Resolution: Make sure that the specified timestamp has been obtained from the participant in some way. If so, retry after a bit (possibly repeatedly).
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

INVALID_ARGUMENT_REPAIR

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

INVALID_STATE_REPAIR_ERROR

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

IO_STREAM_REPAIR_ERROR

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

MANUAL_LOGICAL_SYNCHRONIZER_UPGRADE_ERROR

Explanation: Manual logical synchronizer upgrade failed
Resolution: Retry after operator intervention.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

UNAVAILABLE_ACS_SNAPSHOT

Explanation: The participant does not support serving an ACS snapshot at the requested timestamp because its database has already been pruned, e.g., by the continuous background pruning process.
Resolution: The snapshot at the requested timestamp is no longer available. Pick a more recent timestamp if possible.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.9. LedgerApiErrors

HEAP_MEMORY_OVER_LIMIT

Explanation: This error happens when the JVM heap memory pool exceeds a pre-configured limit.
Resolution: The following actions can be taken: 1. Review the historical use of heap space by inspecting the metric given in the message. 2. Review the current heap space limits configured in the rate limiting configuration. 3. Try to space out requests that are likely to require a large amount of memory to process.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

MAXIMUM_NUMBER_OF_STREAMS

Explanation: This error happens when the number of concurrent gRPC streaming requests exceeds the configured limit.
Resolution: The following actions can be taken: 1. Review the historical need for concurrent streaming by inspecting the metric given in the message. 2. Review the maximum streams limit configured in the rate limiting configuration. 3. Try to space out streaming requests such that they do not need to run in parallel with each other.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

NO_PREFERRED_PACKAGES_FOUND

Explanation: This error occurs if the topology state of the participant’s connected synchronizers cannot satisfy the vetting requirements provided in the request.
Resolution: Inspect the error message and refine the request or retry later. If the error persists, inform the involved counterparties about their invalid topology state.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

NO_VETTED_INTERFACE_IMPLEMENTATION_PACKAGE

Explanation: The requested interface view for the template’s package-name is unavailable due to a missing vetted package. This could be due to a stale stream subscription or the deactivation of an interface implementation resulting from the unvetting of its compatible packages.
Resolution: Close and re-open the stream subscription to refresh the vetting state used for rendering interface views. If the problem persists and it is unexpected, contact the participant operator.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

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 validation requests from other participants through a connected synchronizer. In order to prevent the participant of being overloaded, it will start to reject commands once a certain load threshold is reached. The main threshold is the number of in-flight validation requests that the participant is currently processing. These requests can be caused either by this participant or by other participants. For a submission to be counted as an in-flight validation request, the participant must first observe its sequencing, which means that there is a delay between the submission and the submitted command to be counted towards the currently in-flight validation requests. In order to avoid an overload situation by a sudden burst of commands, the participant will also enforce a rate limit before a submission is accepted for interpretation. This rate limit can be configured with a steady state rate and a burst factor. The burst factor is a multiplier of the steady state rate that allows for a certain number of commands to be submitted in a burst before the rate limit kicks in. As an example, with a rate limit of 1000 commands per second and a burst factor of 2, the rate limit will kick in once 2000 commands have been submitted on top of the commands allowed by the rate limit.
Resolution: Verify the limits configured, the load and the command latency on the participant and adjust if necessary. If the participant is highly loaded, ensure that your application waits some time with the resubmission, preferably with some backoff factor. If possible, ask other participants to send fewer requests; the synchronizer operator can enforce this by imposing a rate limit.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

THREADPOOL_OVERLOADED

Explanation: This happens when the rate of submitted gRPC requests requires more CPU or database power than is available.
Resolution: The following actions can be taken: Here the ‘queue size’ for the threadpool is considered as reported by the executor itself. 1. Review the historical ‘queue size’ growth by inspecting the metric given in the message. 2. Review the maximum ‘queue size’ limits configured in the rate limiting configuration. 3. Try to space out requests that are likely to require a lot of CPU or database power.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

3.10. PruningServiceError

ILLEGAL_ARGUMENT_PRUNING_ERROR

Explanation: Pruning has failed because of an illegal argument.
Resolution: Identify the illegal argument in the error details of the gRPC status message that the call returned.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

NO_INTERNAL_PARTICIPANT_DATA_BEFORE

Explanation: The participant does not hold internal ledger state up to and including the specified time and offset.
Resolution: The participant holds no internal ledger data before or at the time and offset specified as parameters to find_safe_offset. Typically this means that the participant has already pruned all internal data up to the specified time and offset. Accordingly this error indicates that no safe offset to prune could be located prior.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

PURGE_UNKNOWN_SYNCHRONIZER_ERROR

Explanation: Synchronizer purging has been invoked on an unknown synchronizer.
Resolution: Ensure that the specified synchronizer id exists.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SHUTDOWN_INTERRUPTED_PRUNING

Explanation: Pruning has been aborted because the participant is shutting down.
Resolution: After the participant is restarted, the participant ensures that it is in a consistent state. Therefore no intervention is necessary. After the restart, pruning can be invoked again as usual to prune the participant up to the desired offset.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and 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. Generally, you can only prune older events. In particular, the events must be older than the sum of mediator reaction timeout and participant timeout for every synchronizer. And, you can only prune events that are older than the deduplication time configured for this participant. Therefore, if you observe this error, you either just prune older events or you adjust the settings for this participant. The error details field safe_offset contains the highest offset that can currently be pruned, if any.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.11. IndexErrors

3.11.1. DatabaseErrors

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. It is exposed on the API with grpc-status INTERNAL without any details for 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 and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

3.12. PartyManagementServiceError

INVALID_ARGUMENT_PARTY_MANAGEMENT_ERROR

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

INVALID_STATE_PARTY_MANAGEMENT_ERROR

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

INVALID_TIMESTAMP_PARTY_MANAGEMENT_ERROR

Explanation: The participant does not (yet) support serving a ledger offset at the requested timestamp. This may have happened because the ledger state processing has not yet caught up.
Resolution: Ensure the requested timestamp is valid. If so, retry after some time (possibly repeatedly).
Category: InvalidGivenCurrentSystemStateSeekAfterEnd
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status OUT_OF_RANGE including a detailed error message.

IO_STREAM_PARTY_MANAGEMENT_ERROR

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

3.13. ParticipantInspectionServiceError

PARTICIPANT_INSPECTION_ILLEGAL_ARGUMENT_ERROR

Explanation: Inspection has failed because of an illegal argument.
Resolution: Identify the illegal argument in the error details of the gRPC status message that the call returned.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

PARTICIPANT_INSPECTION_INTERNAL_ERROR

Explanation: Inspection 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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

3.14. 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. It is exposed on the API with grpc-status INTERNAL without any details for 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

3.15. CommonErrors

REQUEST_ALREADY_IN_FLIGHT

Explanation: Another request with the same id is already being processed.
Resolution: Listen to the appropriate stream until a result for the in-flight request is published. Alternatively, resubmit the request.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

REQUEST_DEADLINE_EXCEEDED

Explanation: The request has not been submitted for processing as its predefined deadline has expired.
Resolution: Retry the request with a greater deadline.
Category: DeadlineExceededRequestStateUnknown
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status DEADLINE_EXCEEDED including a detailed error message.

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 and exposed on the API with grpc-status DEADLINE_EXCEEDED including a detailed error message.

SERVICE_INTERNAL_ERROR

Explanation: This error occurs if one of the services encountered an unexpected exception.
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

SERVICE_NOT_RUNNING

Explanation: This rejection is given when the requested service is not running. It has not started or has already been shut down.
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 and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

UNSUPPORTED_OPERATION

Explanation: This error category is used to signal that an unimplemented code-path has been triggered by a client or participant operator request.
Resolution: This error is caused by a participant node misconfiguration or by an implementation bug. Resolution requires participant operator intervention.
Category: InternalUnsupportedOperation
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status UNIMPLEMENTED without any details for security reasons.

4. SequencerError

BLOCK_NOT_FOUND

Explanation: This error indicates that no block can be found for the given timestamp.
Resolution: Verify that the timestamp is correct and that the sequencer is healthy.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

INVALID_ACKNOWLEDGEMENT_SIGNATURE

Explanation: This error indicates that the sequencer has detected an invalid acknowledgement request signature. This most likely indicates that the request is bogus and has been created by a malicious sequencer. So it will not get processed.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

INVALID_ACKNOWLEDGEMENT_TIMESTAMP

Explanation: This error indicates that the member has acknowledged a timestamp that is after the events it has received. This violates the sequencing protocol.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

INVALID_ENVELOPE_SIGNATURE

Explanation: This error indicates that the sequencer has detected an invalid envelope signature in the submission request. This most likely indicates that the request is bogus and has been created by a malicious sequencer. So it will not get processed.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

INVALID_LEDGER_EVENT

Explanation: The sequencer has detected that some event that was placed on the ledger cannot be parsed. This may be due to some sequencer node acting maliciously or faulty. The event is ignored and processing continues as usual.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

INVALID_SUBMISSION_REQUEST_SIGNATURE

Explanation: This error indicates that the sequencer has detected an invalid submission request signature. This most likely indicates that the request is bogus and has been created by a malicious sequencer. So it will not get processed.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

MAX_REQUEST_SIZE_EXCEEDED

Explanation: This error means that the request size has exceeded the configured value maxRequestSize.
Resolution: Send smaller requests or increase the maxRequestSize in the synchronizer parameters
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

MAX_SEQUENCING_TIME_EXCEEDED

Explanation: This error indicates that a request was not sequenced because the sequencing time would exceed the max-sequencing-time of the request. This error usually happens if either a participant or mediator node is too slowly responding to requests, or if it is catching up after some downtime. In rare cases, it can happen if the sequencer nodes are massively overloaded. If it happens repeatedly, this information might indicate that there is a problem with the respective participant or mediator node.
Resolution: Inspect the time difference between sequenced and max-sequencing-time. If the time difference is large, then some remote node is catching up but sending messages during catch-up. If the difference is not too large, then the submitting node or this sequencer node might be overloaded.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

MULTIPLE_MEDIATOR_RECIPIENTS

Explanation: This error indicates that the participant is trying to send envelopes to multiple mediators or mediator groups in the same submission request. This most likely indicates that the request is bogus and has been created by a malicious sequencer. So it will not get processed.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

PAYLOAD_TO_EVENT_TIME_BOUND_EXCEEDED

Explanation: This warning indicates that the time difference between storing the payload and writing the” event exceeded the configured time bound, which resulted in the message to be discarded. This can happen during some failure event on the database which causes unexpected delay between these two database operations. (The two events need to be sufficiently close together to support pruning of payloads by timestamp).
Resolution: The submitting node will usually retry the command, but you should check the health of the sequencer node, in particular with respect to database processing.
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

SEQUENCED_BEFORE_OR_AT_LOWER_BOUND

Explanation: This error indicates that a request was not sequenced because the sequencing time of the request would have been before the sequencer’s configured lower bound of the sequencing time.
Resolution: Wait for the time to advance beyond the sequencing time lower bound.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side.

SNAPSHOT_NOT_FOUND

Explanation: This error indicates that no sequencer snapshot can be found for the given timestamp.
Resolution: Verify that the timestamp is correct and that the sequencer is healthy.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

5. SequencerAdministrationError

CANNOT_DISABLE_LOCAL_SEQUENCER_MEMBER

Explanation: Sequencers cannot disable their local subscription as that would disable their ability to adapt to topology changes.
Resolution: Disabling sequencer subscriptions is typically done to facilitate sequencer pruning. If the sequencer’s local subscription prevents sequencer pruning, consider lowering the sequencer time tracker min_observation_duration.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

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

CANNOT_READ_CONFIG_FILES

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 product configuration reference for 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

7. TopologyManagementErrorGroup

7.1. TopologyManagerError

PREVIEW_FEATURE

Explanation: This error indicates that preview features need to be enabled.
Resolution: Set flag enablePreviewFeatures to true and retry.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_CANNOT_REMOVE_MAPPING

Explanation: This error indicates that a mapping cannot be removed.
Resolution: Use the REPLACE operation to change the existing mapping.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_CONFIRMING_THRESHOLD_CANNOT_BE_REACHED

Explanation: This error indicates that the confirming threshold is higher than the number of hosting nodes, which will result in a non functional party.
Resolution: Decrease the threshold or increase the number of hosting nodes.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_DANGEROUS_COMMAND_REQUIRES_FORCE_ALIEN_MEMBER

Explanation: This error indicates that a dangerous command that could break a node was rejected. This is the case if a dangerous command is run on a node to issue transactions for another node. Such commands must be run with force, as they are very dangerous and could easily break the node. 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 the ForceFlag.AlienMember if you really know what you are doing.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_ILLEGAL_REMOVAL_OF_ACTIVE_TRANSACTIONS

Explanation: This error indicates that a participant is trying to rescind actively used topology transactions while still being hosting parties.
Resolution: The participant must remove itself from the party to participant mappings that still refer to it.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_INCONSISTENT_SNAPSHOT

Explanation: This error indicates that the submitted topology snapshot was internally inconsistent.
Resolution: Inspect the transactions mentioned in the transactions field in the error details metadata for inconsistencies.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INCREASE_OF_PREPARATION_TIME_TOLERANCE

Explanation: This error indicates that it has been attempted to increase the preparationTimeRecordTimeTolerance synchronizer parameter in an insecure manner. Increasing this parameter may disable security checks and can therefore be a security risk.
Resolution: Make sure that the new value of preparationTimeRecordTimeTolerance is at most half of the mediatorDeduplicationTimeout synchronizer parameter. Use mySynchronizer.service.set_preparation_time_record_time_tolerance for securely increasing preparationTimeRecordTimeTolerance. Alternatively, add the flag ForceFlag.PreparationTimeRecordTimeToleranceIncrease to your command, if security is not a concern for you. The security checks will be effective again after twice the new value of preparationTimeRecordTimeTolerance. Using ForceFlag.PreparationTimeRecordTimeToleranceIncrease is safe upon synchronizer bootstrapping.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_INSUFFICIENT_KEYS

Explanation: This error indicates that members referenced in a topology transaction have not declared at least one signing key or at least 1 encryption key or both.
Resolution: Ensure that all members referenced in the topology transaction have declared at least one signing key and at least one encryption key, then resubmit the failed transaction. The metadata details of this error contain the members with the missing keys in the field members.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_INVALID_MAPPING

Explanation: This error indicates that the submitted topology mapping was invalid.
Resolution: The participant should work with the owners of the parties mentioned in the parties field in the error details metadata to get itself removed from the list of hosting participants of those parties.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INVALID_OWNER_TO_KEY_MAPPING

Explanation: This error indicates that the provided owner to key mapping does not confirm to the requirements of the synchronizer.
Resolution: Each synchronizer defines the valid set of key specs supported. Any member must provide at least one signing key with the valid specs. Participants must provide also an encryption key.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INVALID_REMOVAL_OF_OWNER_TO_KEY_MAPPING

Explanation: This error indicates the owner to key mapping is still being used by another transaction.
Resolution: Every synchronizer member needs keys before it can be registered. Consequently, the member needs to be removed first before the keys can be removed.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INVALID_SUCCESSOR

Explanation: This error indicates that the successor synchronizer id is not valid.
Resolution: Change the physical synchronizer id of the successor so that it satisfies: - it is greater than the current physical synchronizer id - it is greater than all previous synchronizer announcements
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INVALID_SYNCHRONIZER

Explanation: This error is returned if a transaction was submitted that is restricted to another synchronizer.
Resolution: Recreate the content of the transaction with a correct synchronizer identifier.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_INVALID_TX_SIGNATURE

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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

TOPOLOGY_INVALID_UPGRADE_TIME

Explanation: This error indicates that the synchronizer upgrade announcement specified an invalid upgrade time.
Resolution: Resubmit the synchronizer announcement with an upgrade time sufficiently in the future.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_MANAGER_ALARM

Explanation: The topology manager has received a malformed message from another node.
Resolution: Inspect the error message for details.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

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. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

TOPOLOGY_MAPPING_ALREADY_EXISTS

Explanation: This error indicates that a topology 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 and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_MEDIATORS_ALREADY_IN_OTHER_GROUPS

Explanation: This error indicates that a topology transaction attempts to add mediators to multiple mediator groups.
Resolution: Either first remove the mediators from their current groups or choose other mediators to add.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_MEMBER_CANNOT_REJOIN_SYNCHRONIZER

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

TOPOLOGY_MISSING_MAPPING

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

TOPOLOGY_MULTI_TRANSACTION_HASH_MISMATCH

Explanation: This error is returned when a signature does not cover the expected transaction hash of the transaction.
Resolution: Either add a signature for the hash of this specific transaction only, or a signature that covers the this transaction as part of a multi transaction hash.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_NAMESPACE_ALREADY_IN_USE

Explanation: This error indicates that the namespace is already used by another entity.
Resolution: Change the namespace used in the submitted topology transaction.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_NAMESPACE_HAS_BEEN_REVOKED

Explanation: This error indicates that the namespace has been revoked.
Resolution: Use a different namespace.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_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 you explicitly requested signing with specific keys, then the unusable keys are listed. Otherwise, if the list is empty, then you are missing the certificates.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TOPOLOGY_NO_CORRESPONDING_ACTIVE_TX_TO_REVOKE

Explanation: This error indicates that the attempt to add a removal transaction was rejected, as the mapping affecting the removal did not exist.
Resolution: Inspect the topology state and ensure the mapping 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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_NO_ONGOING_SYNCHRONIZER_UPGRADE

Explanation: This error indicates that a synchronizer upgrade is not ongoing, which prevents some upgrade operations from being performed.
Resolution: Contact the owners of the synchronizer about the ongoing synchronizer upgrade.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_ONGOING_SYNCHRONIZER_UPGRADE

Explanation: This error indicates that a synchronizer upgrade is ongoing and only mappings related to synchronizer upgrade are permitted.
Resolution: Contact the owners of the synchronizer about the ongoing synchronizer upgrade.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_PARTICIPANT_ID_CONFLICT_WITH_PARTY

Explanation: This error indicates that a participant failed to be onboarded, because it has the same UID as an already existing party.
Resolution: Change the identity of the participant by either changing the namespace or the participant’s UID and try to onboard to the synchronizer again.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_PARTICIPANT_ONBOARDING_REFUSED

Explanation: This error indicates that a participant was not able to onboard to a synchronizer because onboarding restrictions are in place.
Resolution: Verify the onboarding restrictions of the synchronizer. If the synchronizer is not locked, then the participant needs first to be put on the allow list by issuing a ParticipantSynchronizerPermission transaction.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_PARTY_ID_CONFLICT_WITH_ADMIN_PARTY

Explanation: This error indicates that the partyId to allocate is the same as an already existing admin party.
Resolution: Submit the topology transaction with a changed partyId.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_REMOVE_MUST_NOT_CHANGE_MAPPING

Explanation: This error indicates that the removal of a topology mapping also changed the content compared to the mapping with the previous serial.
Resolution: Submit the transaction with the same topology mapping as the previous serial, but with the operation REMOVE.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_SERIAL_MISMATCH

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

TOPOLOGY_SIGNING_THRESHOLD_CANNOT_BE_REACHED

Explanation: This error indicates that the signing threshold is higher than the number of signing keys, which will result in a non functional party.
Resolution: Decrease the threshold or increase the number of signing keys.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_STORE_NOT_FOUND

Explanation: This error indicates that the expected topology store was not found.
Resolution: Check that the provided topology store name is correct before retrying.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TOPOLOGY_TEMPORARY_STORE_ALREADY_EXISTS

Explanation: This error indicates that there already exists a temporary topology store with the desired identifier.
Resolution: Either first the existing temporary topology store before resubmitting the request or use the store as it is.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

TOPOLOGY_TOO_MANY_PENDING_TOPOLOGY_TRANSACTIONS

Explanation: This error indicates that currently, too many topology transactions are pending for this node.
Resolution: Change the maximum queue size of the synchronizer outbox or retry.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

TOPOLOGY_TOO_MANY_TRANSACTION_WITH_HASH

Explanation: This error indicates that more than one topology transaction with the same transaction hash was found.
Resolution: Inspect the topology state for consistency and take corrective measures before retrying. The metadata details of this error contains the transactions in the field transactions.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_TRANSACTION_NOT_FOUND

Explanation: This error indicates that a topology transaction could not be found.
Resolution: The topology transaction either has been rejected, is not valid anymore, is not yet valid, or does not yet exist.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TOPOLOGY_UNAUTHORIZED_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 a valid namespace delegations of the signing key exists or upload one before adding this transaction.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

TOPOLOGY_UNKNOWN_MEMBERS

Explanation: This error indicates that the topology transaction references members that are currently unknown.
Resolution: Wait for the onboarding of the members to be become active or remove the unknown members from the topology transaction. The metadata details of this error contain the unknown member in the field members.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TOPOLOGY_VALUE_OUT_OF_BOUNDS

Explanation: This error occurs when the new parameter value is outside the defined lower and upper bounds.
Resolution: Choose a value that is within the allowed lower and upper limits. Alternatively, add the flag ForceFlag.AllowOutOfBoundsValue to force the value change. Caution: Forcing a value change may result in adverse system behaviour. Proceed only if you understand the risks.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

7.1.1. Synchronizer

SYNCHRONIZER_NODE_INITIALISATION_FAILED

Explanation: This error indicates that the initialisation of a synchronizer node failed due to invalid arguments.
Resolution: Consult the error details.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

7.1.1.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: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side.

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.

7.1.2. ParticipantTopologyManagerError

DAML_PRIM_NOT_UTILITY_PACKAGE

Explanation: This error indicates that a package with name daml-prim or daml-std-lib that isn’t a utility package was being vetted. All daml-prim and daml-std-lib packages should be utility packages.
Resolution: Contact the supplier of the Dar.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

EXTERNAL_PARTY_ALREADY_EXISTS

Explanation: This error occurs when a request to allocate an external party is made for a party that already exists.
Resolution: Allocate a new party with unique keys. If you’re trying to change the hosting nodes of the party, follow the party replication procedure instead.
Category: InvalidGivenCurrentSystemStateResourceExists
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ALREADY_EXISTS including a detailed error message.

KNOWN_PACKAGE_VERSION

Explanation: This error indicates that the upgrade checks failed on a package because another package with the same name and version has been previously vetted.
Resolution: Inspect the error message and contact support.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

NOT_VALID_UPGRADE_PACKAGE

Explanation: This error indicates that the package to be vetted is invalid because it doesn’t upgrade the vetted packages it claims to upgrade.
Resolution: Contact the supplier of the DAR or ensure the vetting state change does not lead to simultaneously-vetted upgrade-incompatible packages.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

TOPOLOGY_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: Upload the package locally first before issuing such a transaction.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TOPOLOGY_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 and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_DISABLE_PARTY_WITH_ACTIVE_CONTRACTS

Explanation: This error indicates that a dangerous PartyToParticipant mapping deletion was rejected. If the command is run and there are active contracts where the party is a stakeholder, these contracts will become will never get pruned, resulting in storage that cannot be reclaimed.
Resolution: Set the ForceFlag.PackageVettingRevocation if you really know what you are doing.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_INSUFFICIENT_PERMISSION_FOR_SIGNATORY_PARTY

Explanation: This error indicates that a request to change a participant permission to observer was rejected. If the command is run and the party is still a signatory on active contracts, then this transition prevents it from using the contracts.
Resolution: Set the ForceFlag.AllowInsufficientParticipantPermissionForSignatoryParty if you really know what you are doing.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

TOPOLOGY_INSUFFICIENT_SIGNATORY_ASSIGNING_PARTICIPANTS

Explanation: This error indicates that a dangerous PartyToParticipant mapping was rejected. If the command is run, there will no longer be enough signatory-assigning participants (i.e., reassigning participants with confirmation permissions for assignments) to complete the ongoing reassignments, these reassignments will remain stuck.
Resolution: Set the ForceFlag.AllowInsufficientSignatoryAssigningParticipantsForParty if you really know what you are doing.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

8. CommandErrors

CONSOLE_COMMAND_INTERNAL_ERROR

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

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.

9. CryptoPrivateStoreError

CRYPTO_PRIVATE_STORE_ERROR

Explanation: This error indicates that a key could not be stored.
Resolution: Inspect the error details
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

10. CryptoPublicStoreError

CRYPTO_PUBLIC_STORE_ERROR

Explanation: This error indicates that a key could not be stored.
Resolution: Inspect the error details
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

11. DatabaseStorageError

DB_CONNECTION_LOST

Explanation: This error indicates that the connection to the database has been lost.
Resolution: Inspect error message for details.
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

DB_STORAGE_DEGRADATION

Explanation: This error indicates that degradation of database storage components.
Resolution: This error indicates performance degradation. The error occurs when a database task has been rejected, typically due to having a too small task queue. The task will be retried after a delay. If this error occurs frequently, however, you may want to consider increasing the task queue. (Config parameter: canton.<path-to-my-node>.storage.config.queueSize).
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

12. HandshakeErrors

DEPRECATED_PROTOCOL_VERSION

Explanation: This error is logged or returned if a participant or synchronizer are using deprecated protocol versions. Deprecated protocol versions might not be secure anymore.
Resolution: Migrate to a new synchronizer that uses the most recent protocol version.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

13. MediatorError

DUPLICATE_CONFIRMATION_REQUEST_UUID

Explanation: The mediator keeps track of the UUID of confirmation requests recently processed to detect duplicate submissions. The request has the same UUID as a previous request that has been processed within the deduplication window. The request will be rejected. No corruption of the ledger is to be expected.
Resolution: Re-submit the request with a fresh UUID. Caution that if the earlier request succeeded, a re-submission may lead to duplicate effects.
Category: UnredactedSecurityAlert
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

MEDIATOR_INTERNAL_ERROR

Explanation: Request processing failed due to a violation of internal invariants. It indicates a bug at the mediator.
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

MEDIATOR_INVALID_MESSAGE

Explanation: The mediator has received an invalid message (request or response). The message will be discarded. As a consequence, the underlying request may be rejected. No corruption of the ledger is to be expected. This error is to be expected after a restart or failover of a mediator.
Resolution: Address the cause of the error. Let the submitter retry the command.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

MEDIATOR_PARTICIPANT_EQUIVOCATION

Explanation: A participant has equivocated by submitting contradictory verdicts (Reject and Approve, or vice versa) for the same request and view. This is a serious security concern indicating either a malicious participant or a critical bug in the participant’s software. The second verdict is ignored. No corruption of the ledger is to be expected, but this incident should be investigated.
Resolution: Investigate the participant for misbehavior. Contact support.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

MEDIATOR_RECEIVED_MALFORMED_MESSAGE

Explanation: The mediator has received a malformed message. This may occur due to a bug at the sender of the message. The message will be discarded. As a consequence, the underlying request may be rejected. No corruption of the ledger is to be expected.
Resolution: Contact support.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

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 response timeout. The field “unresponsiveParties” in the error info contains the comma-separated list of parties that failed to send a response within the confirmation response timeout. This field is only present since protocol version 6
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 and exposed on the API with grpc-status ABORTED including a detailed error message.

14. EncryptionKeyCreationError

ENCRYPTION_KEY_CREATION_ERROR

Explanation: This error indicates that an encryption key could not be created.
Resolution: Inspect the error details
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

15. EncryptionKeyGenerationError

ENCRYPTION_KEY_GENERATION_ERROR

Explanation: This error indicates that an encryption key could not be created.
Resolution: Inspect the error details
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

16. EnvelopeOpenerError

EVENT_DESERIALIZATION_ERROR

Explanation: This error indicates that the sequencer client was unable to parse a message. This indicates that the message has been created by a bogus or malicious sender. The message will be dropped.
Resolution: If no other errors are reported, Canton has recovered automatically. You should still consider to start an investigation to understand why the sender has sent an invalid message.
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

17. SignatureCheckError

INCONSISTENT_SIGNATURE_CHECK_ALARM

Explanation: Signature verification passed for a mediator group, but some individual signature checks failed. This situation can occur when the number of valid signatures is sufficient to reach a threshold, even though some signatures were rejected due to mismatches or validation errors. While this does not block progress, it may indicate incorrect or malicious key usage, configuration issues, or a bug in the signing process. The affected signatures were ignored, but the system proceeded.
Resolution: Contact support
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

18. SequencerRateLimitError

INCORRECT_EVENT_COST

Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

19. GrpcVaultServiceError

INVALID_KMS_KEY_ID

Explanation: Selected KMS key id is invalid
Resolution: Specify a valid key id and retry.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

NO_ENCRYPTED_PRIVATE_KEY_STORE_ERROR

Explanation: Node is not running an encrypted private store
Resolution: Verify that an encrypted store and KMS config are set for this node.
Category: InternalUnsupportedOperation
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status UNIMPLEMENTED without any details for security reasons.

REGISTER_KMS_KEY_INTERNAL_ERROR

Explanation: Internal error emitted upon failing to register a KMS key in Canton
Resolution: Contact support
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

WRAPPER_KEY_ALREADY_IN_USE_ERROR

Explanation: Selected wrapper key id for rotation is already in use
Resolution: Select a different key id and retry.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

WRAPPER_KEY_DISABLED_OR_DELETED_ERROR

Explanation: Selected wrapper key id for rotation cannot be used because key is disabled or set to be deleted
Resolution: Specify a key id from an active key and retry.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

WRAPPER_KEY_NOT_EXIST_ERROR

Explanation: Selected wrapper key id for rotation does not match any existing KMS key
Resolution: Specify a key id that matches an existing KMS key and retry.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

WRAPPER_KEY_ROTATION_INTERNAL_ERROR

Explanation: Internal error emitted upon internal wrapper key rotation errors
Resolution: Contact support
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

20. TrafficControlErrors

INVALID_TRAFFIC_CONTROL_PURCHASED_MESSAGE

Explanation: The member received an invalid traffic control message. This may occur due to a bug at the sender of the message. The message will be discarded. As a consequence, the underlying traffic purchased update will not take effect.
Resolution: Contact support
Category: SecurityAlert
Conveyance: This error is logged with log-level WARN on the server side. It is exposed on the API with grpc-status INVALID_ARGUMENT without any details for security reasons.

TRAFFIC_CONTROL_DISABLED

Explanation: Traffic control is not active on the synchronizer.
Resolution: Enable traffic control by setting the traffic control dynamic synchronizer parameter.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TRAFFIC_CONTROL_SERIAL_TOO_LOW

Explanation: The provided serial is lower or equal to the latest recorded balance update.
Resolution: Re-submit the top up request with a serial above the latest recorded balance update.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TRAFFIC_CONTROL_STATE_NOT_FOUND

Explanation: This error indicates that the participant does not have a traffic state.
Resolution: Ensure that the the participant is connected to a synchronizer with traffic control enabled, and that it has received at least one event from the synchronizer since its connection.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

TRAFFIC_CONTROL_TOP_UP_SUBMISSION_FAILED

Explanation: Received an unexpected error when sending a top up submission request for sequencing.
Resolution: Re-submit the top up request with an exponential backoff strategy.
Category: InvalidGivenCurrentSystemStateResourceMissing
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status NOT_FOUND including a detailed error message.

21. SequencerErrors

OUTDATED_TRAFFIC_COST

Explanation: The provided submission cost is outdated compared to the synchronizer state at sequencing time.
Resolution: Re-submit the request with an updated submission cost.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_AGGREGATE_SUBMISSION_ALREADY_SENT

Explanation: This error occurs when the sequencer has already sent out the aggregate submission for the request.
Resolution: This is expected to happen during operation of a system with aggregate submissions enabled. No action required.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_AGGREGATE_SUBMISSION_STUFFING

Explanation: This error occurs when the sequencer already received the same submission request from the same sender.
Resolution: This error indicates that an aggregate submission has already been accepted by the sequencer and for some reason there is a repeated submission. This is likely caused by retrying a submission. This can usually be ignored.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_INTERNAL

Explanation: An internal error occurred on the sequencer.
Resolution: Contact support.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

SEQUENCER_INTERNAL_TESTING

Explanation: An internal error occurred on the sequencer. Can only appear in tests.
Resolution: Contact support.
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

SEQUENCER_MAX_SEQUENCING_TIME_TOO_FAR

Explanation: Maximum sequencing time on the submission request is exceeding the maximum allowed interval into the future. Could be result of a concurrent dynamic synchronizer parameter change for sequencerAggregateSubmissionTimeout.
Resolution: In case there was a recent concurrent dynamic synchronizer parameter change, simply retry the submission. Otherwise this error code indicates a bug in Canton (a faulty node behaviour). Please contact customer support.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_NOT_ENOUGH_TRAFFIC_CREDIT

Explanation: Sequencer has refused a submission request due to insufficient credits in the sender’s traffic purchased entry.
Resolution: Acquire more traffic credits with the system by purchasing traffic credits for the sender.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_OVERLOADED

Explanation: The sequencer is overloaded and cannot handle the request.
Resolution: Retry with exponential backoff.
Category: ContentionOnSharedResources
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status ABORTED including a detailed error message.

SEQUENCER_SENDER_UNKNOWN

Explanation: The senders of the submission request or the eligible senders in the aggregation rule are not known to the sequencer.
Resolution: This indicates a race with topology changes or a bug in Canton (a faulty node behaviour). Please contact customer support if this problem persists.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_SUBMISSION_REQUEST_MALFORMED

Explanation: This error occurs when the sequencer receives an invalid submission request, e.g. it has an aggregation rule with an unreachable threshold. Malformed requests will not emit any deliver event.
Resolution: Check if the sender is running an attack. If you can rule out an attack, please reach out to Canton support.
Category: UnredactedSecurityAlert
Conveyance: This error is logged with log-level WARN on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

SEQUENCER_SUBMISSION_REQUEST_REFUSED

Explanation: This error occurs when the sequencer cannot accept submission request due to the current state of the system.
Resolution: This usually indicates a misconfiguration of the system components or an application bug and requires operator intervention. Please refer to a specific error message to understand the exact cause.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_TOMBSTONE_PERSISTED

Explanation: An onboarded sequencer has put a tombstone in place of an event with a topology timestamp older than the sequencer signing key.
Resolution: Clients should connect to another sequencer with older event history to consume the tombstoned events before reconnecting to the recently onboarded sequencer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_TOPOLOGY_TIMESTAMP_AFTER_SEQUENCING_TIMESTAMP

Explanation: Topology timestamp on the submission request is later than the sequencing time.
Resolution: This indicates a bug in Canton (a faulty node behaviour). Please contact customer support.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_TOPOLOGY_TIMESTAMP_TOO_EARLY

Explanation: Topology timestamp on the submission request is earlier than allowed by the dynamic synchronizer parameters.
Resolution: This indicates a bug in Canton (a faulty node behaviour). Please contact customer support.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

SEQUENCER_UNAVAILABLE

Explanation: The sequencer is currently unavailable.
Resolution: Retry quickly.
Category: TransientServerFailure
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status UNAVAILABLE including a detailed error message.

SEQUENCER_UNIMPLEMENTED

Explanation: This sequencer does not support the requested feature.
Resolution: Contact the sequencer operator.
Category: InternalUnsupportedOperation
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status UNIMPLEMENTED without any details for security reasons.

SEQUENCER_UNKNOWN_RECIPIENTS

Explanation: This error happens when a submission request specifies nodes that are not known to the sequencer.
Resolution: This indicates a bug in Canton (a faulty node behaviour). Please contact customer support.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

22. 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 and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

23. ResilientSequencerSubscription

SEQUENCER_FORK_DETECTED

Explanation: This error is logged when a sequencer client determined a ledger fork, where a sequencer node responded with different events for the same timestamp / counter. Whenever a client reconnects to a synchronizer, it will start with the last message received and compare whether that last message matches the one it received previously. If not, it will report with this error. A ledger fork should not happen in normal operation. It can happen if the backups have been taken in a wrong order and e.g. the participant was more advanced than the sequencer.
Resolution: You can recover by restoring the system with a correctly ordered backup. Please consult the respective sections in the manual.
Category: SystemInternalAssumptionViolated
Conveyance: This error is logged with log-level ERROR on the server side. It is exposed on the API with grpc-status INTERNAL without any details for security reasons.

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 issue does not resolve itself automatically.
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

24. SendAsyncClientError

SEQUENCER_SEND_ASYNC_CLIENT_ERROR

Explanation: This error indicates that a message could not be sent through the sequencer.
Resolution: Inspect the error details
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

25. SequencerSubscriptionError

SEQUENCER_TOMBSTONE_ENCOUNTERED

Explanation: This error indicates that a sequencer subscription to a recently onboarded sequencer attempted to read an event replaced with a tombstone. A tombstone occurs if the timestamp associated with the event predates the validity of the sequencer’s signing key. This error results in the sequencer client disconnecting from the sequencer.
Resolution: Connect to another sequencer with older event history to consume the tombstoned events before reconnecting to the recently onboarded sequencer.
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

26. SigningKeyCreationError

SIGNING_KEY_CREATION_ERROR

Explanation: This error indicates that an encryption key could not be created.
Resolution: Inspect the error details
Category: InvalidGivenCurrentSystemStateOther
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status FAILED_PRECONDITION including a detailed error message.

27. SigningKeyGenerationError

SIGNING_KEY_GENERATION_ERROR

Explanation: This error indicates that a signing key could not be created.
Resolution: Inspect the error details
Category: InvalidIndependentOfSystemState
Conveyance: This error is logged with log-level INFO on the server side and exposed on the API with grpc-status INVALID_ARGUMENT including a detailed error message.

28. 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. For example, a host system clock runs backwards when a clock synchronization method like the Network Time Protocol (NTP) adjusts the clock 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.
Category: BackgroundProcessDegradationWarning
Conveyance: This error is logged with log-level WARN on the server side.

Categories 8 through 12 (InvalidIndependentOfSystemState, InvalidGivenCurrentSystemState*) are typically application-level issues rather than operator-level. If you see them persistently in operator logs, they may indicate configuration problems.

Synchronizer Connectivity Errors

These errors appear when your participant cannot communicate with the synchronizer.

Sequencer Errors

This section will be expanded in a future update. For sequencer-related troubleshooting, see Troubleshooting Methodology.

Mediator Errors

This section will be expanded in a future update. For mediator-related troubleshooting, see Troubleshooting Methodology.

ACS Commitment Errors

Active Contract Set (ACS) commitment errors relate to the integrity checking mechanism that participants use to verify they agree on shared contract state.

Database and Storage Errors

DB_STORAGE_DEGRADATION(13,...): Database task queue is rejecting tasks, usually because the queue is too small for the current workload. Tasks will be retried after a delay. If this occurs frequently, increase the task queue size via canton.<path-to-node>.storage.config.queueSize or improve your database’s I/O capacity (IOPS, storage type). DB_CONNECTION_LOST(13,...): The connection to the database was lost. Check that your PostgreSQL instance is running and reachable, and that connection limits have not been exhausted.

Topology Management Errors

These errors occur when managing topology state — party allocations, package vetting, key management, and synchronizer configuration. TOPOLOGY_UNAUTHORIZED_TRANSACTION(9,...): The topology transaction was not authorized. Verify that the signing key has the required permissions. TOPOLOGY_INSUFFICIENT_KEYS(9,...): Required keys are missing. Ensure the node has the necessary signing and encryption keys registered. TOPOLOGY_INVALID_MAPPING(9,...): The topology mapping is invalid. Check the parameters of the topology transaction you are submitting. TOPOLOGY_MANAGER_ALARM(5,...): A security alert from the topology manager. Investigate and contact support.

Splice-Specific Operational Errors

These errors are specific to Splice validator and SV app operation on the Canton Network. Traffic balance below reserved amount — Your validator app has not been able to purchase traffic. The validator blocks transactions (except traffic purchases) once the balance drops below the reserved threshold. Check logs for TopupMemberTrafficTrigger to find the root cause. If you only want to use free traffic, remove the validator top-up configuration.

    ABORTED: Traffic balance below reserved traffic amount (0 < 200000)

Insufficient funds to buy configured traffic amount — The validator attempted to purchase traffic but does not have enough Canton Coin. New nodes on TestNet and MainNet start with a zero balance and accrue CC through validator liveness rewards over time. You can also receive a CC transfer from another node. If you only want free traffic, remove the validator top-up configuration. Node identity mismatch — You changed the participant identifier after initialization. For validators, the node identifier defaults to validatorPartyHint, so changing that also triggers this error. On a fresh node, you can reset by dropping the databases and restarting. On an established node, revert to the original identifier. MemberDisabled when connecting to sequencer — Your participant has been down longer than the 30-day sequencer pruning window, and the SVs have disabled it. Recover your CC balance by spinning up a new node and re-onboarding.

Error escalation

For the decision path on how to triage and escalate errors, see Error Escalation in the troubleshooting methodology.

Overview

Validator Deployment

Super Validator Deployment

Splice Fundamentals

Canton Console

Production Operations

Extension Synchronizers

Troubleshooting

Release Notes

Reference

Community Resources

Documentation Index

​Reading Error Codes in Logs

​Log Levels

​Error Categories

​Machine Readable Information

​Example

​Error Categories Inventory

​Error Codes Inventory

​1. GrpcErrors

​ABORTED_DUE_TO_SHUTDOWN

​SERVER_OVERLOADED

​2. AuthorizationChecksErrors

​ACCESS_TOKEN_EXPIRED

​INTERNAL_AUTHORIZATION_ERROR

​INVALID_TOKEN

​PERMISSION_DENIED

​STALE_STREAM_AUTHORIZATION

​UNAUTHENTICATED

​3. ParticipantErrorGroup

​3.1. Errors

​ACS_COMMITMENT_INTERNAL_ERROR

​3.1.1. MismatchError

​ACS_COMMITMENT_ALARM

​ACS_COMMITMENT_MISMATCH

​ACS_MISMATCH_NO_SHARED_CONTRACTS

​3.1.2. DegradationError

​ACS_COMMITMENT_DEGRADATION

​ACS_COMMITMENT_DEGRADATION_WITH_INEFFECTIVE_CONFIG

​3.2. AddPartyError

​ADD_PARTY_DISCONNECTED_FROM_SYNCHRONIZER

​ADD_PARTY_OTHER

​3.3. LedgerApiErrorGroup

​3.3.1. CommandExecutionErrors

​DISCLOSED_CONTRACTS_SYNCHRONIZER_ID_MISMATCH

​FAILED_TO_DETERMINE_LEDGER_TIME

​FAILED_TO_EXECUTE_TRANSACTION

​FAILED_TO_PREPARE_TRANSACTION

​INTERPRETATION_TIME_EXCEEDED

​PACKAGE_NAME_DISCARDED_DUE_TO_UNVETTED_PACKAGES

​PACKAGE_SELECTION_FAILED

​PRESCRIBED_SYNCHRONIZER_ID_MISMATCH

​3.3.1.1. Package

​ALLOWED_LANGUAGE_VERSIONS

​PACKAGE_VALIDATION_FAILED

​3.3.1.2. Preprocessing

​COMMAND_PREPROCESSING_FAILED

​3.3.1.3. Interpreter

​CONTRACT_DOES_NOT_IMPLEMENT_INTERFACE

​CONTRACT_DOES_NOT_IMPLEMENT_REQUIRING_INTERFACE

​CONTRACT_HASHING_ERROR

​CONTRACT_ID_COMPARABILITY

​CONTRACT_ID_IN_CONTRACT_KEY

​CONTRACT_NOT_ACTIVE

​CREATE_EMPTY_CONTRACT_KEY_MAINTAINERS

​DAML_AUTHORIZATION_ERROR

​DAML_FAILURE

​DAML_INTERPRETATION_ERROR

​DAML_INTERPRETER_INVALID_ARGUMENT

​DISCLOSED_CONTRACT_KEY_HASHING_ERROR

​FETCH_EMPTY_CONTRACT_KEY_MAINTAINERS

​INTERPRETATION_DEV_ERROR

​INTERPRETATION_USER_ERROR

​MALFORMED_TEXT

​NON_COMPARABLE_VALUES

​TEMPLATE_PRECONDITION_VIOLATED

​UNHANDLED_EXCEPTION

​VALUE_NESTING

​WRONGLY_TYPED_CONTRACT

​3.3.1.3.1. LookupErrors

Reading Error Codes in Logs

Log Levels

Error Categories

Machine Readable Information

Example

Error Categories Inventory

Error Codes Inventory

1. GrpcErrors

ABORTED_DUE_TO_SHUTDOWN

SERVER_OVERLOADED

2. AuthorizationChecksErrors

ACCESS_TOKEN_EXPIRED

INTERNAL_AUTHORIZATION_ERROR

INVALID_TOKEN

PERMISSION_DENIED

STALE_STREAM_AUTHORIZATION

UNAUTHENTICATED

3. ParticipantErrorGroup

3.1. Errors

ACS_COMMITMENT_INTERNAL_ERROR

3.1.1. MismatchError

ACS_COMMITMENT_ALARM

ACS_COMMITMENT_MISMATCH

ACS_MISMATCH_NO_SHARED_CONTRACTS

3.1.2. DegradationError

ACS_COMMITMENT_DEGRADATION

ACS_COMMITMENT_DEGRADATION_WITH_INEFFECTIVE_CONFIG

3.2. AddPartyError

ADD_PARTY_DISCONNECTED_FROM_SYNCHRONIZER

ADD_PARTY_OTHER

3.3. LedgerApiErrorGroup

3.3.1. CommandExecutionErrors

DISCLOSED_CONTRACTS_SYNCHRONIZER_ID_MISMATCH

FAILED_TO_DETERMINE_LEDGER_TIME

FAILED_TO_EXECUTE_TRANSACTION

FAILED_TO_PREPARE_TRANSACTION

INTERPRETATION_TIME_EXCEEDED

PACKAGE_NAME_DISCARDED_DUE_TO_UNVETTED_PACKAGES

PACKAGE_SELECTION_FAILED

PRESCRIBED_SYNCHRONIZER_ID_MISMATCH

3.3.1.1. Package

ALLOWED_LANGUAGE_VERSIONS

PACKAGE_VALIDATION_FAILED

3.3.1.2. Preprocessing

COMMAND_PREPROCESSING_FAILED

3.3.1.3. Interpreter

CONTRACT_DOES_NOT_IMPLEMENT_INTERFACE

CONTRACT_DOES_NOT_IMPLEMENT_REQUIRING_INTERFACE

CONTRACT_HASHING_ERROR

CONTRACT_ID_COMPARABILITY

CONTRACT_ID_IN_CONTRACT_KEY

CONTRACT_NOT_ACTIVE

CREATE_EMPTY_CONTRACT_KEY_MAINTAINERS

DAML_AUTHORIZATION_ERROR

DAML_FAILURE

DAML_INTERPRETATION_ERROR

DAML_INTERPRETER_INVALID_ARGUMENT

DISCLOSED_CONTRACT_KEY_HASHING_ERROR

FETCH_EMPTY_CONTRACT_KEY_MAINTAINERS

INTERPRETATION_DEV_ERROR

INTERPRETATION_USER_ERROR

MALFORMED_TEXT

NON_COMPARABLE_VALUES

TEMPLATE_PRECONDITION_VIOLATED

UNHANDLED_EXCEPTION

VALUE_NESTING

WRONGLY_TYPED_CONTRACT

3.3.1.3.1. LookupErrors

CONTRACT_KEY_NOT_FOUND

UNRESOLVED_PACKAGE_NAME

3.3.1.3.2. CryptoError

INTERPRETATION_CRYPTO_ERROR_MALFORMED_BYTE_ENCODING

INTERPRETATION_CRYPTO_ERROR_MALFORMED_KEY

INTERPRETATION_CRYPTO_ERROR_MALFORMED_SIGNATURE

3.3.1.3.3. UpgradeError

INTERPRETATION_UPGRADE_ERROR_AUTHENTICATION_FAILED

INTERPRETATION_UPGRADE_ERROR_TRANSLATION_FAILED

INTERPRETATION_UPGRADE_ERROR_VALIDATION_FAILED

3.3.2. AdminServicesErrorGroup

3.3.2.1. PartyManagementServiceErrors