Errors

Every error the contract can return, what it means, and what to do. Grouped by who is likely to hit it.

scripts/check-errors.mjs verifies this page covers every variant in the contract's error type, so the two cannot silently drift apart.

Staking and redeeming

Error	What it means	What to do
`contract is paused`	An admin froze stake, redeem and claim	Only the admin can unpause. Positions are unaffected
`deposit would take the pool to X, above the Y cap`	The deposit cap is full	Stake less, or wait — redemptions free up room
`stake amount is too small to mint any vATOM at the current exchange rate`	Your deposit rounds to zero shares	Stake more
`zero amount`	Amount was zero, or below a configured minimum	Send a real amount
`expected exactly one coin with denom X`	Wrong denom, no funds, or several coins attached	Attach exactly one coin of the named denom
`insufficient vATOM sent`	Redeem needs the receipt token attached as funds	Attach vATOM
`insufficient pooled liquidity`	The redemption exceeds what the pool can back	Redeem less
`rewards vault is not configured; call SetRewardsVault before staking`	Deployment is incomplete — staking is gated on the vault	An admin must bind the vault
`no recognized backing for the outstanding supply; minting is refused in this state`	vATOM exists but no recognised backing — the rate is undefined	Do not deposit. Operators should investigate immediately
`the pool holds X with no receipts outstanding, so it belongs to no one`	The pool is non-empty while no vATOM exists. Minting 1:1 would hand that ATOM to you	Should be unreachable. Report it — it needs governance, not a deposit
`a previous cohort is still winding down: X of redemptions are unsettled`	Everyone has exited and their batches have not all finalized. Deposits are closed until they do, so the departing cohort's rewards cannot be inherited	Wait, and keep finalizing batches

Privileged actions

Error	What it means	What to do
`unauthorized`	The sender is neither the admin nor, for a guardian message, the guardian	Send from the right key
`invalid config: guardian and clear_guardian cannot both be set`	One request asked to appoint a guardian and to remove one	Send one or the other
`a deposit cap can only be lowered by a guardian: X is not below Y`	A guardian tried to raise the cap, or set it to what it already is. The guardian's powers only ever shrink	Use the admin to raise a cap
`a guardian may only remove validators, and X is not in the current set`	The named validator is not configured — usually a mistyped address	Check the address against `config`
`validator set cannot be empty`	Removing those validators would leave none, and the contract could not stake at all	Leave at least one, or pause instead
`new delegation is halted until an admin reviews the validator set a guardian reduced`	A guardian removed validators, so `stake` and `restake_rewards` wait for an admin to declare a set. Redeeming and claiming are unaffected	Wait for the admin's `update_validators`
`redelegation destination X is not in the configured validator set`	Redelegation may only move stake to a validator the allocation already uses	Add it with `update_validators` first, or pick one that is configured
`cannot redelegate to the same validator`	Source and destination are identical	Nothing to do — check the addresses

Claiming

Error	What it means	What to do
`unbond batch must be finalized before it can be claimed`	Your ATOM has arrived but the batch is not settled	Anyone can finalize, including you
`withdrawal is not claimable yet`	Still unbonding	Wait for the date shown
`withdrawal already claimed`	Already paid out	Nothing to do
`withdrawal not found`	No such request id	Check the id

Keeper operations

Error	What it means	What to do
`a reward vesting window is still active; restake again once it has elapsed`	Compounding refused mid-window	Wait. Rewards accumulate in the vault; nothing is lost
`no vATOM is outstanding, so a reward fold has no one to vest to`	Everyone has exited; folding would put unowned ATOM in the pool for the next depositor to capture	Nothing needed — the next cohort's first stake disposes of it to the community pool automatically. `SweepOrphanedRewards` does the same when nobody is depositing
`vATOM is outstanding, so the vault balance belongs to current holders`	`SweepOrphanedRewards` called while holders exist	Use `RestakeRewards`; the vault is theirs
`unbond batch is not ready to process yet`	The batch window has not elapsed	Wait, or call again later. Harmless
`unbond batch is empty`	No requests to process	Nothing to do
`unbond batch has not been processed yet`	Tried to finalize a batch still open	Process it first
`unbond batch slashing has already been finalized`	Already settled	Nothing to do
`unbond batch not found`	No such batch id	Check the id
`validator X already has the maximum in-flight unbonding entries`	The Cosmos 7-entry-per-validator limit	Finalize an earlier batch to release a slot, then retry
`another in-flight batch's unbonding has already completed…`	Two batches have arrived; the balance cannot be attributed	Use the governed path for all arrived batches together
`batch N has a forecast (not chain-reported) maturity…`	The chain did not report a completion time	Needs the governed settlement path

Governed settlement

Error	What it means	What to do
`this call must settle every batch whose ATOM has arrived, together`	A subset was supplied	Include every batch the error names
`the requested credits total X but only Y is unreserved`	Credits exceed the available balance	Recompute per-batch realized amounts; they must fit the unreserved balance
`batch N has begun arriving but is not settleable until T`	A partially arrived batch blocks settlement	Wait until the time given, then retry
`batch N has a forecast maturity and you are crediting…`	Crediting less than full backing on a forecast batch	Only set `accept_shortfall` once you have established the loss is real — claims settle permanently
`no batches supplied; an empty settlement is not a settlement`	Empty list	Supply the arrived batches
`slashing_effect must be in [0, 1]; a haircut never increases the payout`	Out-of-range value	Use a fraction between 0 and 1

Configuration

Error	What it means	What to do
`unauthorized`	Not the admin	Use the admin key
`validator weights must sum to 10000 basis points`	Weights are wrong	Make them total exactly 10000
`max_validators must be between 1 and N`	Out of range	Use a value within the ceiling
`N validators exceeds the configured max_validators of M`	Set too large	Reduce the set or raise `max_validators`
`this set plus the validators still holding a live delegation would be N, above the hard ceiling`	A rotation would leave more validators with live delegations than the gas budget allows. `ProcessUnbondBatch` iterates live delegations, not the configured list	Drain the outgoing validators — process unbond batches until their delegations are gone — before rotating further
`validator set is empty`	No validators supplied	Supply at least one
`validator X is not in the chain's bonded validator set`	A validator is unbonded, jailed or unknown	Remove it or use a bonded one
`protocol fee must be zero for this free-to-use contract`	A non-zero fee was supplied	It is fixed at zero by design
`invalid configuration: …`	A parameter failed validation	The message names the parameter
`the address is not an immutable rewards-vault (expected code id) owned by this contract`	The candidate vault failed verification	It must run the expected code id, have no migrate admin, and be owned by this contract
`the currently configured rewards vault still holds a balance`	Re-pointing would strand funds	Sweep with `RestakeRewards` first

Migration

Error	What it means
`cannot migrate from contract X`	Wrong contract — the stored cw2 name does not match
`cannot downgrade from version X to Y`	Downgrades are refused
`cannot migrate from version X; minimum supported is Y`	Storage from before the minimum does not deserialize. Deploy fresh
`stored version X is not three numeric components`	The stored version cannot be parsed, so the downgrade and compatibility checks cannot be evaluated. Refused rather than skipped — an unparseable version previously bypassed both

Internal

These indicate a bug or a chain-level surprise, not user error. Report them.

Error	What it means
`unexpected reply id N`	A submessage reply arrived that the contract does not recognise
`math overflow`	An arithmetic operation exceeded its bounds — the contract refuses rather than wrapping
`the contract holds X but Y is already reserved for finalized claims`	The claim reserve exceeds the contract's balance, which should be impossible: the reserve is only ever incremented from that balance and decremented when paid out. Both settlement routes refuse rather than normalising it to zero and writing an irreversible result over a broken invariant

Errors ​

Staking and redeeming ​

Privileged actions ​

Claiming ​

Keeper operations ​

Governed settlement ​

Configuration ​

Migration ​

Internal ​

See also ​