Skip to main content
For the complete documentation index, see llms.txt

Error reference

Midnight.js exposes structured error classes so you can classify failures when working with contracts and transactions.

This reference highlights the error classes and their properties.

Quick reference​

ClassKindTrigger
TxFailedErrorTransactionConsensus rejected or failed to apply a transaction
DeployTxFailedErrorTransactionDeploy transaction failed
CallTxFailedErrorTransactionCall transaction failed
ReplaceMaintenanceAuthorityTxFailedErrorTransactionMaintenance authority replacement failed
RemoveVerifierKeyTxFailedErrorTransactionVerifier key removal failed
InsertVerifierKeyTxFailedErrorTransactionVerifier key insertion failed
ContractTypeErrorContractDeployed contract type or verifier keys do not match expectations
IncompleteCallTxPrivateStateConfigConfigurationprivateStateId set without privateStateProvider on a call
IncompleteFindContractPrivateStateConfigConfigurationinitialPrivateState set without privateStateId on a find
ScopedTransactionIdentityMismatchErrorState / identityScoped batch reused cache for a different contract or private state

Transaction errors​

These errors occur when a submitted transaction fails during execution or validation.

Transaction failed (TxFailedError)​

An error indicating that a transaction submitted to a consensus node failed.

Properties​

  • finalizedTxData: Finalization data of the failed transaction
  • circuitId (optional): Circuit(s) used to construct the transaction

Deploy transaction failed (DeployTxFailedError)​

An error indicating that a contract deployment transaction failed.

Properties​

finalizedTxData: Finalization data of the failed deployment transaction.

Call transaction failed (CallTxFailedError)​

An error indicating that a contract call transaction failed.

Properties​

  • finalizedTxData: Finalization data of the failed call transaction
  • circuitId: Circuit(s) used to build the transaction

Replace maintenance authority transaction failed (ReplaceMaintenanceAuthorityTxFailedError)​

An error indicating that a maintenance authority replacement transaction failed.

Properties​

finalizedTxData: Finalization data of the failed maintenance authority replacement transaction.

Remove verifier key transaction failed (RemoveVerifierKeyTxFailedError)​

An error indicating that a verifier key removal transaction failed.

Properties​

finalizedTxData: Finalization data of the failed verifier key removal transaction.

Insert verifier key transaction failed (InsertVerifierKeyTxFailedError)​

An error indicating that a verifier key insertion transaction failed.

Properties​

finalizedTxData: Finalization data of the failed verifier key insertion transaction.

Contract errors​

These errors occur when interacting with deployed contracts.

Contract type error (ContractTypeError)​

An error indicating that the expected contract type does not match the deployed contract state.

Properties​

  • contractState: The deployed contract state
  • circuitIds: Undefined circuits or circuits with mismatched verifier keys

Configuration errors​

These errors indicate invalid or incomplete configuration when building transactions or querying contracts.

Incomplete call transaction private state config (IncompleteCallTxPrivateStateConfig)​

An error indicating that a call transaction specifies a privateStateId but does not provide a privateStateProvider.

Properties​

  • privateStateId: The private state ID specified in the call transaction
  • privateStateProvider: The private state provider specified in the call transaction

Incomplete find contract private state config (IncompleteFindContractPrivateStateConfig)​

An error indicating that a contract lookup specifies an initialPrivateState but does not include a privateStateId.

Properties​

  • initialPrivateState: The initial private state specified in the contract lookup
  • privateStateId: The private state ID specified in the contract lookup

Message​

Here is the exact runtime message the client throws when this error occurs:

'initialPrivateState' was defined for contract find while 'privateStateId' was undefined

State and identity errors​

These errors help prevent subtle bugs related to contract identity and cached state.

Scoped transaction identity mismatch (ScopedTransactionIdentityMismatchError)​

An error indicating that a scoped transaction attempts to reuse cached state with a different contract address or private state ID.

Properties​

  • cached: The cached contract address and private state ID
  • requested: The requested contract address and private state ID

Error handling​

Use JavaScript's try/catch syntax and the instanceof operator to handle errors:

import { CallTxFailedError } from '@midnight-ntwrk/midnight-js-contracts';

try {
  await client.call(/* ... */);
} catch (error) {
  if (error instanceof CallTxFailedError) {
    console.error('Transaction failed:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}