Errors

This document outlines the recommended usage and APIs for error handling in Cosmos SDK modules.

Modules are encouraged to define and register their own errors to provide better context on failed message or handler execution. Typically, these errors should be common or general errors which can be further wrapped to provide additional specific execution context.

Registration

Modules should define and register their custom errors in x/{module}/errors.go. Registration of errors is handled via the errors package (opens new window).

Example:

Copy package types import ( sdkerrors "github.com/cosmos/cosmos-sdk/types/errors" ) // x/distribution module sentinel errors var ( ErrEmptyDelegatorAddr = sdkerrors.Register(ModuleName, 2, "delegator address is empty") ErrEmptyWithdrawAddr = sdkerrors.Register(ModuleName, 3, "withdraw address is empty") ErrEmptyValidatorAddr = sdkerrors.Register(ModuleName, 4, "validator address is empty") ErrEmptyDelegationDistInfo = sdkerrors.Register(ModuleName, 5, "no delegation distribution info") ErrNoValidatorDistInfo = sdkerrors.Register(ModuleName, 6, "no validator distribution info") ErrNoValidatorCommission = sdkerrors.Register(ModuleName, 7, "no validator commission to withdraw") ErrSetWithdrawAddrDisabled = sdkerrors.Register(ModuleName, 8, "set withdraw address disabled") ErrBadDistribution = sdkerrors.Register(ModuleName, 9, "community pool does not have sufficient coins to distribute") ErrInvalidProposalAmount = sdkerrors.Register(ModuleName, 10, "invalid community pool spend proposal amount") ErrEmptyProposalRecipient = sdkerrors.Register(ModuleName, 11, "invalid community pool spend proposal recipient") ErrNoValidatorExists = sdkerrors.Register(ModuleName, 12, "validator does not exist") ErrNoDelegationExists = sdkerrors.Register(ModuleName, 13, "delegation does not exist") )

Each custom module error must provide the codespace, which is typically the module name (e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code provide a globally unique Cosmos SDK error. Typically, the code is monotonically increasing but does not necessarily have to be. The only restrictions on error codes are the following:

• Must be greater than one, as a code value of one is reserved for internal errors.
• Must be unique within the module.

Note, the Cosmos SDK provides a core set of common errors. These errors are defined in types/errors/errors.go (opens new window).

Wrapping

The custom module errors can be returned as their concrete type as they already fulfill the error interface. However, module errors can be wrapped to provide further context and meaning to failed execution.

Example:

Copy func (k BaseKeeper) DelegateCoins(ctx sdk.Context, delegatorAddr, moduleAccAddr sdk.AccAddress, amt sdk.Coins) error { moduleAcc := k.ak.GetAccount(ctx, moduleAccAddr) if moduleAcc == nil { return sdkerrors.Wrapf(sdkerrors.ErrUnknownAddress, "module account %s does not exist", moduleAccAddr) } if !amt.IsValid() { return sdkerrors.Wrap(sdkerrors.ErrInvalidCoins, amt.String()) } balances := sdk.NewCoins() for _, coin := range amt { balance := k.GetBalance(ctx, delegatorAddr, coin.GetDenom()) if balance.IsLT(coin) { return sdkerrors.Wrapf( sdkerrors.ErrInsufficientFunds, "failed to delegate; %s is smaller than %s", balance, amt, ) } balances = balances.Add(balance) err := k.setBalance(ctx, delegatorAddr, balance.Sub(coin)) if err != nil { return err } } if err := k.trackDelegation(ctx, delegatorAddr, balances, amt); err != nil { return sdkerrors.Wrap(err, "failed to track delegation") } // emit coin spent event ctx.EventManager().EmitEvent( types.NewCoinSpentEvent(delegatorAddr, amt), ) err := k.addCoins(ctx, moduleAccAddr, amt) if err != nil { return err } return nil }

Regardless if an error is wrapped or not, the Cosmos SDK's errors package provides a function to determine if an error is of a particular kind via Is.

ABCI

If a module error is registered, the Cosmos SDK errors package allows ABCI information to be extracted through the ABCIInfo function. The package also provides ResponseCheckTx and ResponseDeliverTx as auxiliary functions to automatically get CheckTx and DeliverTx responses from an error.