Reference
Errors and recovery
Common program errors, their causes, and the appropriate recovery action.
Nest rejects an instruction when the supplied state or pricing does not satisfy the program constraints. Most of these errors should update the UI state rather than trigger an automatic retry loop.
| Rejection | Meaning | Safe response |
|---|---|---|
| Protocol or market paused | An administrator or emergency breaker disabled the action | Disable the action and refresh on-chain flags |
| Stale / invalid oracle | Price age, confidence, feed, signature, or instruction proof failed | Fetch a new payload and rebuild the whole transaction |
| Borrow LTV exceeded | Mint or withdrawal would leave debt above the market's borrow limit | Reduce output, add collateral, or repay debt |
| Debt or deposit cap exceeded | A per-vault, market, or protocol cap would be crossed | Display remaining capacity; do not retry unchanged |
| Insufficient collateral / token balance | Wallet or vault cannot fund the requested raw amount | Refresh balances and reduce the amount |
| Bad debt outstanding | Risk-sensitive PSM or staking actions are temporarily unavailable | Disable the action until on-chain bad debt is zero |
| Stake capacity exceeded | The requested deposit would exceed supported staking capacity | Quote a smaller stake from current state |
| Unstake minimum output not met | The current net nUSD value is below min_nusd_out | Refresh state, show the new quote, and require confirmation |
| Unstake amount too small | Rounding or the one-day target-APR fee leaves no transferable nUSD | Increase the share amount; do not submit a zero output bound |
| PSM outflow breaker / idle liquidity | Swap-out exceeds the rolling limit or available USDC | Show it as temporarily unavailable; do not bypass it |
Preserve simulation logs
const simulation = await connection.simulateTransaction(transaction);
if (simulation.value.err) {
const diagnostic = {
error: simulation.value.err,
logs: simulation.value.logs ?? [],
unitsConsumed: simulation.value.unitsConsumed,
};
// Show a friendly mapped error to the user. Send this diagnostic only to a
// redacted application logger; never attach wallet secrets or RPC URLs.
throw new Error(JSON.stringify(diagnostic));
}After a blockhash expires, rebuild and re-simulate from fresh account state.
Do not only replace recentBlockhash: deadlines, balances, debt, oracle values,
and output quotes may all have changed.