Errors

insufficient_balance

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

View as Markdown

The signing account cannot cover the requested amount, fee, or stake requirement.

This covers several chain-side variants: free TAO too low for a transfer or fee, an unstake/move larger than free stake (or locked by conviction/collateral), a withdrawal that would drop below the existential deposit, or a hotkey below the stake floor needed to set weights / children.

Check with btcli wallet balance and btcli stake list, then reduce the amount, fund the coldkey, unlock/wait out locks, or stake more to the hotkey — the exact error name in the diagnostic says which.

Remediation

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

Chain errors

The exact chain error names (from the extrinsic receipt) that classify to insufficient_balance; the description says what triggered the failure and where to check. Each name has its own page:

Chain errorDescription
BalanceLowThe sender's mapped account cannot cover the transaction's value plus maximum gas fee, detected during validation or when withdrawing the fee. Check the account balance against value plus gas_limit times the effective gas price.
BalanceWithdrawalErrorThe requested TAO could not be withdrawn from the coldkey's free balance, typically due to insufficient funds, the existential deposit, or frozen/reserved balance. Check the coldkey's balance with btcli wallet balance and reduce the amount or top up.
CannotAffordLockCostThe coldkey's free balance cannot cover the current dynamic subnet-creation lock cost. Compare btcli subnets create-cost (or btcli query subnet-registration-cost) against the coldkey balance from btcli wallet balance before registering a subnet.
ExistentialDepositThe amount is too small to create the destination account: its resulting balance would sit below the existential deposit. Compare the transfer value plus the destination's current free balance against the ExistentialDeposit constant.
ExpendabilityThe transfer or payment would drop the sender below the existential deposit and kill the account while keep-alive semantics are required. Compare the sender's free balance minus the amount and fees against ExistentialDeposit, or use transfer_allow_death if reaping is acceptable.
InsufficientAlphaBalanceA stake decrease asked to debit more alpha than the hotkey-coldkey pair holds on that subnet. Compare the requested amount against the pair's current stake on the netuid (btcli stake list or the Alpha storage entry).
InsufficientBalanceThe caller's spendable balance is below what the operation needs, whether a plain transfer, a crowdloan deposit or contribution, or a swap. Compare the account's free balance in System.Account (net of holds, freezes, and fees) against the amount being moved.
InsufficientStakeForLockThe requested lock amount exceeds the coldkey's total alpha stake on that subnet (existing locked mass included). Compare the amount against the coldkey's stake on the netuid, e.g. via btcli stake list, and lock less or add stake first.
InsufficientTaoBalanceThe coldkey's free TAO balance is below the amount a TAO-side operation needs: a transfer between coldkeys, a burn or recycle, or a subnet-registration lock. Check the coldkey's balance with btcli wallet balance against the amount being moved.
LiquidityRestrictionsThe withdrawal is blocked by locks or freezes on the account even though the raw balance looks sufficient. Check the account's Locks and Freezes entries and compare the frozen amount against what would remain after the withdrawal.
NotEnoughBalanceToPaySwapColdKeyThe coldkey's free TAO balance cannot cover the coldkey swap cost, which is recycled when the swap executes. Check the balance with btcli wallet balance against the swap cost and top up before btcli wallet swap-coldkey.
NotEnoughBalanceToPaySwapHotKeyThe coldkey's free TAO balance is below the hotkey swap cost (a per-subnet cost applies when swapping on a single netuid). Check btcli wallet balance against the key swap cost and fund the coldkey before retrying.
NotEnoughBalanceToStakeThe coldkey's free balance is less than the TAO required, either the stake amount in add_stake or the burn cost of a registration. Check btcli wallet balance against the amount or the current registration burn (Burn storage for the netuid).
NotEnoughStakeThe caller's hotkey holds less stake than the action requires; a generic insufficient-stake failure on staking-related calls. Check the hotkey's stake on the relevant subnet, e.g. btcli stake list, against the amount the extrinsic needs.
NotEnoughStakeToSetChildkeysRaised by set_children when the parent hotkey's total stake is below StakeThreshold and it is not the subnet owner hotkey. Compare the hotkey's total stake (btcli stake list) against the StakeThreshold storage value.
NotEnoughStakeToSetWeightsSetting or committing weights failed because the hotkey's stake weight on the subnet is below StakeThreshold (the weights-min-stake floor); the subnet owner hotkey is exempt. Check the hotkey's stake on that netuid against StakeThreshold.
NotEnoughStakeToWithdrawAn unstake, stake move, swap, or transfer requested more alpha than the hotkey-coldkey pair holds on that subnet. Compare the requested amount against that specific position (btcli stake list) — conviction locks are coldkey-wide, so stake may sit on a different hotkey than the lock target; move stake onto the origin hotkey first or pass the hotkey that actually holds the balance.
StakeTooLowForRootRetired. root_register used to raise this when the root network was full and the hotkey's netuid-0 stake did not exceed the lowest-staked root member; root admission is now burn-based (the coldkey pays the root burn price), so this error is no longer raised.
StakeUnavailableAn unstake or same-subnet stake transfer would dip into stake that is still reserved: the requested alpha exceeds the coldkey's free balance on that subnet after subtracting conviction Lock and any miner registration collateral locked against hotkeys the coldkey owns. Check Lock and MinerCollateral for the netuid; only total stake minus those reservations can move.
StorageDepositNotEnoughFundsThe origin's free balance cannot cover the storage deposit limit specified or required for this call. Check the caller's withdrawable balance against the storage_deposit_limit argument and the dry-run's reported deposit.
TransferFailedA balance transfer performed during the contract call failed, most likely because the sender lacks enough free balance. Check the transferring account's free balance against the value being sent, accounting for the existential deposit.
UnlockAmountTooHighAn unlock requested more alpha than remains locked for the coldkey on that subnet. Check the lock's remaining decaying locked mass in the Lock storage entry and request at most that amount.
VestingBalanceThe account's balance is locked under a vesting schedule, leaving too little usable balance to send the requested value. Check the account's Vesting schedules and its lock in Locks, and compare the unvested (still locked) amount against what the transfer needs.
WithdrawFailedWithdrawing the transaction fee from the sender's mapped account failed even though the balance check passed, e.g. due to locks, holds, or existential deposit constraints. Check the account's locks and its free versus withdrawable balance.
ZeroBalanceAfterWithdrawnWithdrawing TAO from the coldkey (e.g. paying a registration burn or adding stake) would leave the account at zero, below what keeps it alive. Check the coldkey's free balance and leave at least the existential deposit after the amount withdrawn.

The same explanation is available in the terminal: btcli explain insufficient_balance (or btcli explain <ChainErrorName> for one exact chain error).