Errors

Every failure carries a machine-readable code and a remediation hint.

A failed execute returns an ExtrinsicResult whose error has a semantic code (branch on it) and a remediation hint (what to try next). Every chain error name is deliberately classified — a CI gate keeps the mapping complete in both directions. The machine-readable version is at /catalog/errors.json.

Error codes

`insufficient_balance`

Fund the signing account or reduce the amount; check with btcli wallet balance

`insufficient_liquidity`

The pool cannot absorb this trade; reduce the amount or split it into smaller steps

`rate_limited`

Wait for the rate-limit window to pass, then retry

`not_registered`

`not_authorized`

Sign with the key or origin that owns the target object, then retry

`already_exists`

The object or state already exists; treat the goal as met or pick a different target

`not_found`

The referenced object is not on-chain; check the identifier

`subnet_not_exists`

Use an existing netuid; btcli subnets list shows valid ones

`subtoken_disabled`

The subnet is not active yet; wait for start_call

`disabled`

This call or feature is switched off on this network

`too_early`

The required window has not opened yet; wait some blocks and retry

`expired`

The window has closed; restart the flow with fresh state

`limit_exceeded`

A chain-side capacity limit was hit; reduce the size or count of the request

`unit_mismatch`

Match the Balance netuid to the operation's currency

`invalid_argument`

Check the argument values against the operation schema

`policy_violation`

The action exceeds a configured safety policy

`internal`

A chain-side invariant failed; nothing to fix client-side — report it if it persists

`unknown`

Inspect the message for details

Chain error classification

The exact chain error name (from the extrinsic receipt) maps to a code:

Chain error	Code
`AccountNotAllowedCommit`	`not_authorized`
`AccountRejectsLockedAlpha`	`invalid_argument`
`ActiveLockExists`	`already_exists`
`ActivityCutoffFactorMilliOutOfBounds`	`invalid_argument`
`ActivityCutoffTooLow`	`invalid_argument`
`AddStakeBurnRateLimitExceeded`	`rate_limited`
`AdminActionProhibitedDuringWeightsWindow`	`too_early`
`AllNetworksInImmunity`	`too_early`
`AlphaHighTooLow`	`invalid_argument`
`AlphaLowOutOfRange`	`invalid_argument`
`AlreadyApproved`	`already_exists`
`AlreadyDeposited`	`already_exists`
`AlreadyFinalized`	`already_exists`
`AlreadyNoted`	`already_exists`
`AlreadyStored`	`already_exists`
`AmountTooLow`	`invalid_argument`
`AnnouncedColdkeyHashDoesNotMatch`	`invalid_argument`
`AnnouncementDepositInvariantViolated`	`internal`
`ArithmeticOverflow`	`internal`
`AutoEpochAlreadyImminent`	`already_exists`
`BadEncKeyLen`	`invalid_argument`
`BalanceLow`	`insufficient_balance`
`BalanceWithdrawalError`	`insufficient_balance`
`BeneficiaryDoesNotOwnHotkey`	`not_authorized`
`BlockDurationTooLong`	`invalid_argument`
`BlockDurationTooShort`	`invalid_argument`
`BondsMovingAverageMaxReached`	`limit_exceeded`
`CallDisabled`	`disabled`
`CallFiltered`	`not_authorized`
`CallUnavailable`	`not_found`
`CanNotSetRootNetworkWeights`	`invalid_argument`
`CannotAddSelfAsDelegateDependency`	`invalid_argument`
`CannotAffordLockCost`	`insufficient_balance`
`CannotBurnOrRecycleOnRootSubnet`	`invalid_argument`
`CannotEndInPast`	`invalid_argument`
`CannotReleaseYet`	`too_early`
`CannotUseSystemAccount`	`not_authorized`
`CapNotRaised`	`too_early`
`CapRaised`	`limit_exceeded`
`CapTooLow`	`invalid_argument`
`ChainIdMismatch`	`invalid_argument`
`ChangePending`	`already_exists`
`ChildParentInconsistency`	`invalid_argument`
`CodeInUse`	`invalid_argument`
`CodeInfoNotFound`	`not_found`
`CodeNotFound`	`not_found`
`CodeRejected`	`invalid_argument`
`CodeTooLarge`	`limit_exceeded`
`ColdKeyAlreadyAssociated`	`already_exists`
`ColdkeySwapAlreadyDisputed`	`already_exists`
`ColdkeySwapAnnounced`	`already_exists`
`ColdkeySwapAnnouncementNotFound`	`not_found`
`ColdkeySwapClearTooEarly`	`too_early`
`ColdkeySwapDisputed`	`not_authorized`
`ColdkeySwapReannouncedTooEarly`	`too_early`
`ColdkeySwapTooEarly`	`too_early`
`CommitRevealDisabled`	`disabled`
`CommitRevealEnabled`	`disabled`
`CommittingWeightsTooFast`	`rate_limited`
`ContractNotFound`	`not_found`
`ContractReverted`	`internal`
`ContractTrapped`	`internal`
`ContributionPeriodEnded`	`expired`
`ContributionPeriodNotEnded`	`too_early`
`ContributionTooLow`	`invalid_argument`
`CreateOriginNotAllowed`	`not_authorized`
`CurrencyError`	`internal`
`DeadAccount`	`not_found`
`DecodingFailed`	`invalid_argument`
`DelegateDependencyAlreadyExists`	`already_exists`
`DelegateDependencyNotFound`	`not_found`
`DelegateTakeTooHigh`	`invalid_argument`
`DelegateTakeTooLow`	`invalid_argument`
`DelegateTxRateLimitExceeded`	`rate_limited`
`DeltaZero`	`invalid_argument`
`DepositCannotBeWithdrawn`	`invalid_argument`
`DepositTooLow`	`invalid_argument`
`Deprecated`	`disabled`
`DisabledTemporarily`	`disabled`
`DrandConnectionFailure`	`internal`
`Duplicate`	`already_exists`
`DuplicateChild`	`invalid_argument`
`DuplicateContract`	`already_exists`
`DuplicateOffenceReport`	`already_exists`
`DuplicateOrderInBatch`	`invalid_argument`
`DuplicateUids`	`invalid_argument`
`DynamicTempoBlockedByCommitReveal`	`disabled`
`Entered`	`already_exists`
`EpochTriggerAlreadyPending`	`already_exists`
`EvmKeyAssociateRateLimitExceeded`	`rate_limited`
`ExistentialDeposit`	`insufficient_balance`
`ExistingVestingSchedule`	`already_exists`
`Exited`	`already_exists`
`ExpectedBeneficiaryOrigin`	`not_authorized`
`Expendability`	`insufficient_balance`
`ExpiredWeightCommit`	`expired`
`FailedToExtractRuntimeVersion`	`invalid_argument`
`FailedToSchedule`	`internal`
`FaucetDisabled`	`disabled`
`FeeOverflow`	`internal`
`FeeRateTooHigh`	`invalid_argument`
`FirstEmissionBlockNumberAlreadySet`	`already_exists`
`GasLimitTooHigh`	`invalid_argument`
`GasLimitTooLow`	`invalid_argument`
`GasPriceTooLow`	`invalid_argument`
`HotKeyAccountNotExists`	`not_registered`
`HotKeyAlreadyDelegate`	`already_exists`
`HotKeyAlreadyRegisteredInSubNet`	`already_exists`
`HotKeyNotRegisteredInNetwork`	`not_registered`
`HotKeyNotRegisteredInSubNet`	`not_registered`
`HotKeySetTxRateLimitExceeded`	`rate_limited`
`HotKeySwapOnSubnetIntervalNotPassed`	`rate_limited`
`IncorrectCommitRevealVersion`	`invalid_argument`
`IncorrectPartialFillAmount`	`invalid_argument`
`IncorrectWeightVersionKey`	`invalid_argument`
`Indeterministic`	`invalid_argument`
`InputForwarded`	`invalid_argument`
`InputLengthsUnequal`	`invalid_argument`
`InsufficientBalance`	`insufficient_balance`
`InsufficientInputAmount`	`invalid_argument`
`InsufficientLiquidity`	`insufficient_liquidity`
`InsufficientStakeForLock`	`insufficient_balance`
`InvalidCallFlags`	`invalid_argument`
`InvalidChainId`	`invalid_argument`
`InvalidChild`	`invalid_argument`
`InvalidChildkeyTake`	`invalid_argument`
`InvalidCrowdloanId`	`not_found`
`InvalidDerivedAccount`	`invalid_argument`
`InvalidDerivedAccountId`	`invalid_argument`
`InvalidDifficulty`	`invalid_argument`
`InvalidEquivocationProof`	`invalid_argument`
`InvalidFinalizationConfig`	`invalid_argument`
`InvalidIdentity`	`invalid_argument`
`InvalidIpAddress`	`invalid_argument`
`InvalidIpType`	`invalid_argument`
`InvalidKeyOwnershipProof`	`invalid_argument`
`InvalidLeaseBeneficiary`	`invalid_argument`
`InvalidLiquidityValue`	`invalid_argument`
`InvalidNonce`	`invalid_argument`
`InvalidNumRootClaim`	`invalid_argument`
`InvalidOrigin`	`not_authorized`
`InvalidPort`	`invalid_argument`
`InvalidRecoveredPublicKey`	`invalid_argument`
`InvalidRevealCommitHashNotMatch`	`invalid_argument`
`InvalidRevealRound`	`expired`
`InvalidRootClaimThreshold`	`invalid_argument`
`InvalidRoundNumber`	`invalid_argument`
`InvalidSchedule`	`invalid_argument`
`InvalidSeal`	`invalid_argument`
`InvalidSignature`	`invalid_argument`
`InvalidSpecName`	`invalid_argument`
`InvalidSubnetNumber`	`invalid_argument`
`InvalidTickRange`	`invalid_argument`
`InvalidValue`	`invalid_argument`
`InvalidVotingPowerEmaAlpha`	`invalid_argument`
`InvalidWorkBlock`	`invalid_argument`
`IssuanceDeactivated`	`disabled`
`LeaseCannotEndInThePast`	`invalid_argument`
`LeaseDoesNotExist`	`not_found`
`LeaseHasNoEndBlock`	`invalid_argument`
`LeaseHasNotEnded`	`too_early`
`LeaseNetuidNotFound`	`not_found`
`LimitOrdersDisabled`	`disabled`
`LiquidAlphaDisabled`	`disabled`
`LiquidityRestrictions`	`insufficient_balance`
`LockHotkeyMismatch`	`invalid_argument`
`MaxAllowedUIdsLessThanCurrentUIds`	`invalid_argument`
`MaxAllowedUidsGreaterThanDefaultMaxAllowedUids`	`invalid_argument`
`MaxAllowedUidsLessThanMinAllowedUids`	`invalid_argument`
`MaxCallDepthReached`	`limit_exceeded`
`MaxContributionReached`	`limit_exceeded`
`MaxContributorsReached`	`limit_exceeded`
`MaxDelegateDependenciesReached`	`limit_exceeded`
`MaxValidatorsLargerThanMaxUIds`	`invalid_argument`
`MaxWeightExceeded`	`limit_exceeded`
`MaxWeightTooLow`	`invalid_argument`
`MaximumContributionTooLow`	`invalid_argument`
`MechanismDoesNotExist`	`subnet_not_exists`
`MigrationInProgress`	`too_early`
`MinAllowedUidsGreaterThanCurrentUids`	`invalid_argument`
`MinAllowedUidsGreaterThanMaxAllowedUids`	`invalid_argument`
`MinimumContributionTooHigh`	`invalid_argument`
`MinimumContributionTooLow`	`invalid_argument`
`MinimumThreshold`	`invalid_argument`
`MultiBlockMigrationsOngoing`	`too_early`
`Named`	`invalid_argument`
`NeedWaitingMoreBlocksToStarCall`	`too_early`
`NegativeSigmoidSteepness`	`invalid_argument`
`NetworkTxRateLimitExceeded`	`rate_limited`
`NeuronNoValidatorPermit`	`not_authorized`
`NewColdKeyIsHotkey`	`invalid_argument`
`NewHotKeyIsSameWithOld`	`invalid_argument`
`NewHotKeyNotCleanForRootSwap`	`invalid_argument`
`NoApprovalsNeeded`	`invalid_argument`
`NoChainExtension`	`disabled`
`NoContribution`	`not_found`
`NoDeposit`	`not_found`
`NoExistingLock`	`not_found`
`NoMigrationPerformed`	`invalid_argument`
`NoNeuronIdAvailable`	`limit_exceeded`
`NoPermission`	`not_authorized`
`NoSelfProxy`	`invalid_argument`
`NoTimepoint`	`invalid_argument`
`NoWeightsCommitFound`	`not_found`
`NonAssociatedColdKey`	`not_authorized`
`NonDefaultComposite`	`invalid_argument`
`NonZeroRefCount`	`invalid_argument`
`NoneValue`	`not_found`
`NotAllowed`	`not_authorized`
`NotAuthorized`	`not_authorized`
`NotConfigured`	`disabled`
`NotEnoughAlphaOutToRecycle`	`insufficient_liquidity`
`NotEnoughBalanceToPaySwapColdKey`	`insufficient_balance`
`NotEnoughBalanceToPaySwapHotKey`	`insufficient_balance`
`NotEnoughBalanceToStake`	`insufficient_balance`
`NotEnoughStake`	`insufficient_balance`
`NotEnoughStakeToSetChildkeys`	`insufficient_balance`
`NotEnoughStakeToSetWeights`	`insufficient_balance`
`NotEnoughStakeToWithdraw`	`insufficient_balance`
`NotFound`	`not_found`
`NotNoted`	`not_found`
`NotOwner`	`not_authorized`
`NotPermittedOnRootSubnet`	`invalid_argument`
`NotProxy`	`not_authorized`
`NotReadyToDissolve`	`too_early`
`NotRequested`	`not_found`
`NotRootSubnet`	`invalid_argument`
`NotSubnetOwner`	`not_authorized`
`NothingAuthorized`	`not_found`
`OrderAlreadyProcessed`	`already_exists`
`OrderCancelled`	`expired`
`OrderExpired`	`expired`
`OrderNetUidMismatch`	`invalid_argument`
`OutOfBounds`	`invalid_argument`
`OutOfGas`	`limit_exceeded`
`OutOfTransientStorage`	`limit_exceeded`
`OutputBufferTooSmall`	`invalid_argument`
`Overflow`	`internal`
`POWRegistrationDisabled`	`disabled`
`PalletHotkeyNotRegistered`	`not_registered`
`PartialFillsNotEnabled`	`disabled`
`PauseFailed`	`invalid_argument`
`PaymentOverflow`	`internal`
`PreLogExists`	`invalid_argument`
`PriceConditionNotMet`	`too_early`
`PriceLimitExceeded`	`insufficient_liquidity`
`ProportionOverflow`	`invalid_argument`
`PulseVerificationError`	`invalid_argument`
`RandomSubjectTooLong`	`limit_exceeded`
`ReentranceDenied`	`invalid_argument`
`Reentrancy`	`internal`
`RegistrationNotPermittedOnRootSubnet`	`invalid_argument`
`RegistrationPriceLimitExceeded`	`limit_exceeded`
`RelayerMissMatch`	`invalid_argument`
`RelayerRequiredForPartialFill`	`invalid_argument`
`Requested`	`invalid_argument`
`RequireSudo`	`not_authorized`
`RescheduleNoChange`	`invalid_argument`
`ReservesOutOfBalance`	`insufficient_liquidity`
`ReservesTooLow`	`insufficient_liquidity`
`ResumeFailed`	`invalid_argument`
`RevealPeriodTooLarge`	`invalid_argument`
`RevealPeriodTooSmall`	`invalid_argument`
`RevealTooEarly`	`too_early`
`RootNetUidNotAllowed`	`invalid_argument`
`RootNetworkDoesNotExist`	`subnet_not_exists`
`SameAutoStakeHotkeyAlreadySet`	`already_exists`
`SameNetuid`	`invalid_argument`
`SenderInSignatories`	`invalid_argument`
`ServingRateLimitExceeded`	`rate_limited`
`SettingWeightsTooFast`	`rate_limited`
`SignatoriesOutOfOrder`	`invalid_argument`
`SlippageTooHigh`	`insufficient_liquidity`
`SpaceLimitExceeded`	`rate_limited`
`SpecVersionNeedsToIncrease`	`invalid_argument`
`StakeTooLowForRoot`	`insufficient_balance`
`StakeUnavailable`	`insufficient_balance`
`StakingRateLimitExceeded`	`rate_limited`
`StateChangeDenied`	`not_authorized`
`StorageDepositLimitExhausted`	`limit_exceeded`
`StorageDepositNotEnoughFunds`	`insufficient_balance`
`StorageOverflow`	`internal`
`SubNetRegistrationDisabled`	`disabled`
`SubnetDoesNotExist`	`subnet_not_exists`
`SubnetLimitReached`	`limit_exceeded`
`SubnetNotExists`	`subnet_not_exists`
`SubtokenDisabled`	`subtoken_disabled`
`SwapInputTooLarge`	`insufficient_liquidity`
`SwapReturnedZero`	`insufficient_liquidity`
`SymbolAlreadyInUse`	`already_exists`
`SymbolDoesNotExist`	`not_found`
`TargetBlockNumberInPast`	`invalid_argument`
`TempoOutOfBounds`	`invalid_argument`
`TerminatedInConstructor`	`internal`
`TerminatedWhileReentrant`	`invalid_argument`
`TooBig`	`limit_exceeded`
`TooFew`	`invalid_argument`
`TooFewSignatories`	`invalid_argument`
`TooMany`	`limit_exceeded`
`TooManyCalls`	`limit_exceeded`
`TooManyChildren`	`limit_exceeded`
`TooManyFieldsInCommitmentInfo`	`limit_exceeded`
`TooManyFreezes`	`limit_exceeded`
`TooManyHolds`	`limit_exceeded`
`TooManyPendingExtrinsics`	`limit_exceeded`
`TooManyRegistrationsThisBlock`	`rate_limited`
`TooManyRegistrationsThisInterval`	`rate_limited`
`TooManyReserves`	`limit_exceeded`
`TooManySignatories`	`limit_exceeded`
`TooManyTopics`	`limit_exceeded`
`TooManyUIDsPerMechanism`	`limit_exceeded`
`TooManyUnrevealedCommits`	`limit_exceeded`
`TooSoon`	`rate_limited`
`TransactionMustComeFromEOA`	`not_authorized`
`TransactorAccountShouldBeHotKey`	`not_authorized`
`TransferDisallowed`	`disabled`
`TransferFailed`	`insufficient_balance`
`TrimmingWouldExceedMaxImmunePercentage`	`limit_exceeded`
`TxChildkeyTakeRateLimitExceeded`	`rate_limited`
`TxRateLimitExceeded`	`rate_limited`
`UidMapCouldNotBeCleared`	`internal`
`UidVecContainInvalidOne`	`invalid_argument`
`UidsLengthExceedUidsInSubNet`	`limit_exceeded`
`UnableToRecoverPublicKey`	`invalid_argument`
`Unannounced`	`too_early`
`Unauthorized`	`not_authorized`
`Undefined`	`internal`
`Underflow`	`internal`
`UnexpectedTimepoint`	`invalid_argument`
`UnexpectedUnreserveLeftover`	`internal`
`UnlockAmountTooHigh`	`insufficient_balance`
`Unproxyable`	`not_authorized`
`Unreachable`	`internal`
`UnverifiedPulse`	`invalid_argument`
`ValueNotInBounds`	`invalid_argument`
`ValueTooLarge`	`limit_exceeded`
`VestingBalance`	`insufficient_balance`
`VotingPowerTrackingNotEnabled`	`disabled`
`WeightExceedsAbsoluteMax`	`limit_exceeded`
`WeightVecLengthIsLow`	`invalid_argument`
`WeightVecNotEqualSize`	`invalid_argument`
`WithdrawFailed`	`insufficient_balance`
`WrongTimepoint`	`invalid_argument`
`XCMDecodeFailed`	`invalid_argument`
`ZeroBalanceAfterWithdrawn`	`insufficient_balance`
`ZeroShareInBatch`	`invalid_argument`