Skip to main content
Anchor program errors surface as numeric codes in transaction logs. Kimia’s Codama-generated clients turn them into typed enums, but you still need a strategy for:
  • Detecting which program the error came from
  • Mapping it to a user-facing message
  • Deciding between retry, prompt, or give-up

Shape of an Anchor error in logs

Program CU3A8MLxrJsz4CiahcduqubCA2WrniiVS4jdovxyyjR6 invoke [1]
Program log: Instruction: RecordStep3
Program log: AnchorError occurred. Error Code: TargetRateNotAchievable. Error Number: 6001. Error Message: Target rate not achievable.
Program CU3A8MLxrJsz4CiahcduqubCA2WrniiVS4jdovxyyjR6 consumed 22345 of 200000 compute units
Kimia clients parse the Error Number and the emitting program ID to route errors to the right enum.

Parsing helper

import {
  isKimiaPerpError,
  KIMIA_PERP_ERROR__STALE_ORACLE,
  KIMIA_PERP_ERROR__INSUFFICIENT_FREE_COLLATERAL,
  KIMIA_PERP_ERROR__SLIPPAGE_EXCEEDED,
} from '@/app/generated/perp/errors';

export function toUserMessage(err: unknown): string {
  if (isKimiaPerpError(err, KIMIA_PERP_ERROR__STALE_ORACLE)) {
    return 'Price feed is stale. Please try again.';
  }
  if (isKimiaPerpError(err, KIMIA_PERP_ERROR__INSUFFICIENT_FREE_COLLATERAL)) {
    return 'Not enough free collateral. Cancel open orders or deposit more.';
  }
  if (isKimiaPerpError(err, KIMIA_PERP_ERROR__SLIPPAGE_EXCEEDED)) {
    return 'Price moved too much before filling. Raise max slippage or reduce size.';
  }
  // ... fall-through cases
  return 'Transaction failed. See logs for details.';
}
See frontend/app/lib/errors.ts for the full mapping the reference UI uses.

Error categories by program

kimia-perp (6000..6199)

BucketCodesTypical recovery
Oracle6000-6002Retry (auto-reposts Hermes update)
Market lifecycle6010-6012Wait for admin / switch market
Margin6020-6022Deposit more collateral, reduce size
Position6030-6033Fix size / direction
Funding6040-6041Wait for the funding period to elapse
Liquidation6050-6051Account not liquidatable (healthy)
Deposit/withdraw6060-6061Amount > 0; enough balance
Math6070Reduce size; hits u128 intermediates
Auth6080-6081Use authority wallet; delegate can’t withdraw
Slippage6090Raise max_slippage_bps
Insurance6100Bad debt; market paused until admin
Orderbook6110-6117Book full, order not found, crossing post-only, market-order slippage
Spot pool6130-6133Pool paused, insufficient liquidity, swap slippage, zero amount

delta-vault

ErrorRecovery
VaultNotActiveWait for admin resume
VaultNotPausedAdmin-only paths require paused state
PerpsUserAccountNotInitCall init_perps_user_account once
NavCorruptedAdmin admin_resync_nav; shouldn’t happen in normal ops
DeltaExceedsThresholdSpot/perp legs have diverged more than the rebalance cap
VaultNotMigratedAdmin must run admin_setup_spot_leg before first deposit

split-engine

ErrorRecovery
NotMaturedWait until maturity timestamp
AlreadyMaturedUse redeem_pt instead of deposit
NoYieldToClaimNothing to claim yet; call update_rewards first
SupplyInvariantViolatedProtocol bug, do not ignore; report it
ZeroDepositDeposit amount must be greater than zero

yield-amm

ErrorRecovery
SwapDisabledNearMaturityToo close to maturity; just redeem_pt
SlippageExceededRaise min_amount_out tolerance
InsufficientLiquidityLarger size than pool supports
EmptyPoolPool hasn’t been seeded yet
InvariantViolatedPost-swap invariant check failed — retry with smaller size

intent-router

ErrorRecovery
InvalidSessionStateStep must follow Created → Step1 → Step2 → Step3
TargetRateNotAchievableLower target, or wait for AMM to recover
TargetRateNotAchievedAchieved rate was below target at step 3; session stays at Step2Complete
PtBalanceMismatchStep 2 can’t account for expected PT
NegativeDiscountPT redeemed for more than face value
InvalidDurationSession duration must be greater than zero

Retry policy

Auto-retryable errors:
  • StaleOracle, re-fetch Hermes, rebuild tx, retry.
  • RPC transient errors (connection, blockhash not found), exponential backoff.
User-prompt errors:
  • SlippageExceeded, ask the user to raise slippage tolerance.
  • InsufficientFreeCollateral, prompt a deposit or cancel-orders flow.
Give up / show error:
  • MarketNotActive, VaultNotActive, nothing the user can do until admin.
  • Math errors (MathOverflow), your input was too large; don’t retry.

Logging raw errors

For unknown or unmapped errors, log:
  • Transaction signature
  • Program logs (tx.meta.logMessages)
  • Which instruction in the tx failed (Anchor logs Instruction: X)
Include these three artefacts in any bug report.