Errors
insufficient_balance
Fund the signing account or reduce the amount; check with `btcli wallet balance`
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 error | Description |
|---|---|
BalanceLow | The 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. |
BalanceWithdrawalError | The 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. |
CannotAffordLockCost | The 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. |
ExistentialDeposit | The 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. |
Expendability | The 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. |
InsufficientAlphaBalance | A 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). |
InsufficientBalance | The 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. |
InsufficientStakeForLock | The 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. |
InsufficientTaoBalance | The 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. |
LiquidityRestrictions | The 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. |
NotEnoughBalanceToPaySwapColdKey | The 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. |
NotEnoughBalanceToPaySwapHotKey | The 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. |
NotEnoughBalanceToStake | The 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). |
NotEnoughStake | The 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. |
NotEnoughStakeToSetChildkeys | Raised 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. |
NotEnoughStakeToSetWeights | Setting 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. |
NotEnoughStakeToWithdraw | An 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. |
StakeTooLowForRoot | Retired. 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. |
StakeUnavailable | An 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. |
StorageDepositNotEnoughFunds | The 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. |
TransferFailed | A 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. |
UnlockAmountTooHigh | An 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. |
VestingBalance | The 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. |
WithdrawFailed | Withdrawing 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. |
ZeroBalanceAfterWithdrawn | Withdrawing 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).