Skip to main content

Handle Errors in Aptos

This page catalogs common errors encountered in the Aptos blockchain and explains how to resolve them wherever possible. As with all software, the code itself is the source of truth for error handling and will always contain entries not found here. Instead, this matrix aims to help you address those errors most typically found, misunderstood, or both.

For the sources of these errors, see:

Help us update this list by sending pull requests containing the errors you encounter. If you don't know how to resolve the error, as described int the Action column, simply leave it blank.

Move Virtual Machine (VM)

ErrorMeaning
UNKNOWN_VALIDATION_STATUSWe don't want the default value to be valid.
INVALID_SIGNATUREThe transaction has a bad signature.
INVALID_AUTH_KEYBad account authentication key.
SEQUENCE_NUMBER_TOO_OLDSequence number is too old.
SEQUENCE_NUMBER_TOO_NEWSequence number is too new.
INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEEInsufficient balance to pay minimum transaction fee.
TRANSACTION_EXPIREDThe transaction has expired.
SENDING_ACCOUNT_DOES_NOT_EXISTThe sending account does not exist.
REJECTED_WRITE_SETThis write set transaction was rejected because it did not meet the requirements for one.
INVALID_WRITE_SETThis write set transaction cannot be applied to the current state.
EXCEEDED_MAX_TRANSACTION_SIZELength of program field in raw transaction exceeded max length.
UNKNOWN_SCRIPTThis script is not in our allowlist of scripts.
UNKNOWN_MODULETransaction is trying to publish a new module.
MAX_GAS_UNITS_EXCEEDS_MAX_GAS_UNITS_BOUNDMax gas units submitted with transaction exceeds max gas units bound in VM.
MAX_GAS_UNITS_BELOW_MIN_TRANSACTION_GAS_UNITSMax gas units submitted with transaction not enough to cover the intrinsic cost of the transaction.
GAS_UNIT_PRICE_BELOW_MIN_BOUNDGas unit price submitted with transaction is below minimum gas price set in the VM.
GAS_UNIT_PRICE_ABOVE_MAX_BOUNDGas unit price submitted with the transaction is above the maximum gas price set in the VM.
INVALID_GAS_SPECIFIERGas specifier submitted is either malformed (not a valid identifier), or does not refer to an accepted gas specifier.
SENDING_ACCOUNT_FROZENThe sending account is frozen.
UNABLE_TO_DESERIALIZE_ACCOUNTUnable to deserialize the account blob.
CURRENCY_INFO_DOES_NOT_EXISTThe currency info was unable to be found.
INVALID_MODULE_PUBLISHERThe account sender doesn't have permissions to publish modules.
NO_ACCOUNT_ROLEThe sending account has no role.
BAD_CHAIN_IDThe transaction's chain_id does not match the one published on-chain.
SEQUENCE_NUMBER_TOO_BIGThe sequence number is too large and would overflow if the transaction were executed.
BAD_TRANSACTION_FEE_CURRENCYThe gas currency is not registered as a TransactionFee currency.
FEATURE_UNDER_GATINGThe feature requested is intended for a future Diem version instead of the current one.
SECONDARY_KEYS_ADDRESSES_COUNT_MISMATCHThe number of secondary signer addresses is different from the number of secondary public keys provided.
SIGNERS_CONTAIN_DUPLICATESThere are duplicates among signers, including the sender and all the secondary signers.
SEQUENCE_NONCE_INVALIDThe sequence nonce in the transaction is invalid (too new, too old, or already used).
CHAIN_ACCOUNT_INFO_DOES_NOT_EXISTThere was an error when accessing chain-specific account information.
MODULE_ADDRESS_DOES_NOT_MATCH_SENDERthe module publisher is not the account that will eventually hold the module.
ZERO_SIZED_STRUCTReported when a struct has zero fields.
DUPLICATE_MODULE_NAMEThe sender is trying to publish two modules with the same name in one transaction.
BACKWARD_INCOMPATIBLE_MODULE_UPDATEThe sender is trying to publish a module that breaks the compatibility checks.
CYCLIC_MODULE_DEPENDENCYThe updated module introduces a cyclic dependency (i.e., A uses B and B also uses A).
INVALID_FRIEND_DECL_WITH_SELFCannot mark the module itself as a friend.
INVALID_FRIEND_DECL_WITH_MODULES_OUTSIDE_ACCOUNT_ADDRESSCannot declare modules outside of account address as friends.
INVALID_FRIEND_DECL_WITH_MODULES_IN_DEPENDENCIESCannot declare modules that this module depends on as friends.
CYCLIC_MODULE_FRIENDSHIPThe updated module introduces a cyclic friendship (i.e., A friends B and B also friends A).
INVALID_PHANTOM_TYPE_PARAM_POSITIONA phantom type parameter was used in a non-phantom position.
LOOP_MAX_DEPTH_REACHEDLoops are too deeply nested.
TYPE_RESOLUTION_FAILUREFailed to resolve type due to linking being broken after verification.
RESOURCE_DOES_NOT_EXISTWe tried to access a resource that does not exist under the account.
RESOURCE_ALREADY_EXISTSWe tried to create a resource under an account where that resource already exists.
UNKNOWN_STATUSA reserved status to represent an unknown vm status. This is std::u64::MAX, but we can't pattern match on that, so put the hardcoded value in.
LINKER_ERRORThis may be due to the function has not been published on chain or by trying to call an invalid function as the result of either an incorrect account address, module name, or function name. This might not happen locally if the sources are available locally but have yet to be published on-chain.

|

Move Standard Library (stdlib)

ErrorMeaning
INVALID_ARGUMENTCaller specified an invalid argument (http: 400).
OUT_OF_RANGEAn input or result of a computation is out of range (http: 400).
INVALID_STATEThe system is not in a state where the operation can be performed (http: 400).
UNAUTHENTICATEDRequest not authenticated due to missing, invalid, or expired auth token (http: 401).
PERMISSION_DENIEDThe client does not have sufficient permission (http: 403).
NOT_FOUNDA specified resource is not found (http: 404).
ABORTEDConcurrency conflict, such as read-modify-write conflict (http: 409).
ALREADY_EXISTSThe resource that a client tried to create already exists (http: 409).
RESOURCE_EXHAUSTEDOut of gas or other forms of quota (http: 429).
CANCELLEDRequest cancelled by the client (http: 499).
INTERNALInternal error (http: 500).
NOT_IMPLEMENTEDFeature not implemented (http: 501).
UNAVAILABLEThe service is currently unavailable. Indicates that a retry could solve the issue (http: 503).

Aptos accounts

ErrorMeaning
EACCOUNT_ALREADY_EXISTSAccount already exists.
EACCOUNT_DOES_NOT_EXISTAccount does not exist.
ESEQUENCE_NUMBER_TOO_BIGSequence number exceeds the maximum value for a u64.
EMALFORMED_AUTHENTICATION_KEYThe provided authentication key has an invalid length.
ECANNOT_RESERVED_ADDRESSCannot create account because address is reserved.
EOUT_OF_GASTransaction exceeded its allocated max gas.
EWRONG_CURRENT_PUBLIC_KEYSpecified current public key is not correct.
EINVALID_PROOF_OF_KNOWLEDGESpecified proof of knowledge required to prove ownership of a public key is invalid.
ENO_CAPABILITYThe caller does not have a digital-signature-based capability to call this function.
EINVALID_ACCEPT_ROTATION_CAPABILITYThe caller does not have a valid rotation capability offer from the other account.
ENO_VALID_FRAMEWORK_RESERVED_ADDRESSAddress to create is not a valid reserved address for Aptos framework.
EINVALID_SCHEMESpecified scheme required to proceed with the smart contract operation - can only be ED25519_SCHEME(0) OR MULTI_ED25519_SCHEME(1).
EINVALID_ORIGINATING_ADDRESSAbort the transaction if the expected originating address is different from the originating address on-chain.
ENO_SUCH_SIGNER_CAPABILITYThe signer capability doesn't exist at the given address.

Aptos coins

ErrorMeaning
ECOIN_INFO_ADDRESS_MISMATCHAddress of account which is used to initialize a coin CoinType doesn't match the deployer of module.
ECOIN_INFO_ALREADY_PUBLISHEDCoinType is already initialized as a coin.
ECOIN_INFO_NOT_PUBLISHEDCoinType hasn't been initialized as a coin.
ECOIN_STORE_ALREADY_PUBLISHEDAccount already has CoinStore registered for CoinType.
ECOIN_STORE_NOT_PUBLISHEDAccount hasn't registered CoinStore for CoinType.
EINSUFFICIENT_BALANCENot enough coins to complete transaction.
EDESTRUCTION_OF_NONZERO_TOKENCannot destroy non-zero coins.
EZERO_COIN_AMOUNTCoin amount cannot be zero.
EFROZENCoinStore is frozen. Coins cannot be deposited or withdrawn.
ECOIN_SUPPLY_UPGRADE_NOT_SUPPORTEDCannot upgrade the total supply of coins to different implementation.
ECOIN_NAME_TOO_LONGName of the coin is too long.
ECOIN_SYMBOL_TOO_LONGSymbol of the coin is too long.

Aptos tokens

ErrorMeaning
EALREADY_HAS_BALANCEThe token has balance and cannot be initialized.
ECOLLECTIONS_NOT_PUBLISHEDThere isn't any collection under this account.
ECOLLECTION_NOT_PUBLISHEDCannot find collection in creator's account.
ECOLLECTION_ALREADY_EXISTSThe collection already exists.
ECREATE_WOULD_EXCEED_COLLECTION_MAXIMUMExceeds the collection's maximal number of token_data.
EINSUFFICIENT_BALANCEInsufficient token balance.
EINVALID_TOKEN_MERGECannot merge the two tokens with different token IDs.
EMINT_WOULD_EXCEED_TOKEN_MAXIMUMExceed the token data maximal allowed.
ENO_BURN_CAPABILITYNo burn capability.
ETOKEN_DATA_ALREADY_EXISTSTokenData already exists.
ETOKEN_DATA_NOT_PUBLISHEDTokenData not published.
ETOKEN_STORE_NOT_PUBLISHEDTokenStore doesn't exist.
ETOKEN_SPLIT_AMOUNT_LARGER_THAN_TOKEN_AMOUNTCannot split token to an amount larger than its amount.
EFIELD_NOT_MUTABLEThe field is not mutable.
ENO_MUTATE_CAPABILITYNot authorized to mutate.
ENO_TOKEN_IN_TOKEN_STOREToken not in the token store.
EUSER_NOT_OPT_IN_DIRECT_TRANSFERUser didn't opt-in direct transfer.
EWITHDRAW_ZEROCannot withdraw 0 token.
ENFT_NOT_SPLITABLECannot split a token that only has 1 amount.
ENO_MINT_CAPABILITYNo mint capability
ECOLLECTION_NAME_TOO_LONGThe collection name is too long.
ENFT_NAME_TOO_LONGThe NFT name is too long.
EURI_TOO_LONGThe URI is too long.
ENO_DEPOSIT_TOKEN_WITH_ZERO_AMOUNTCannot deposit a token with 0 amount.
ENO_BURN_TOKEN_WITH_ZERO_AMOUNTCannot burn 0 token.
EWITHDRAW_PROOF_EXPIRESWithdraw proof expires.
EOWNER_CANNOT_BURN_TOKENToken is not burnable by owner.
ECREATOR_CANNOT_BURN_TOKENToken is not burnable by creator.
ECANNOT_UPDATE_RESERVED_PROPERTYReserved fields for token contract. Cannot be updated by user.
EURI_TOO_SHORTURI too short.
ETOKEN_OFFER_NOT_EXISTToken offer doesn't exist.