Error Codes#

Complete reference for all 44 Coalesce Finance program error codes, organized by category.

Error Code Categories Overview#

Range	Category	Description
0-4	Initialization	Protocol and market setup errors
5-9	Authorization	Permission and access control errors
10-16	Account Validation	PDA and account ownership errors
17-20	Input Validation	Parameter and timestamp errors
21-27	Balance/Capacity	Insufficient funds and limits errors
28-35	Market State	Lifecycle and settlement errors
36-40	Fee/Withdrawal	Fee collection and excess withdrawal errors
41-43	Operational	Runtime, slippage, and haircut errors

Complete Error Reference#

Initialization Errors (0-4)#

Code	Name	Description
0	`AlreadyInitialized`	ProtocolConfig already exists
1	`InvalidFeeRate`	Fee rate exceeds 10,000 bps (100%)
2	`InvalidCapacity`	max_total_supply is 0
3	`InvalidMaturity`	Maturity not in future (< now + 60s)
4	`MarketAlreadyExists`	Market PDA already initialized

Authorization Errors (5-9)#

Code	Name	Description
5	`Unauthorized`	Signer lacks required authority
6	`NotWhitelisted`	Borrower not in whitelist
7	`Blacklisted`	Address is on global blacklist
8	`ProtocolPaused`	Protocol is paused
9	`BorrowerHasActiveDebt`	Cannot modify borrower with outstanding debt

Account Validation Errors (10-16)#

Code	Name	Description
10	`InvalidAddress`	Required address is zero pubkey
11	`InvalidMint`	Mint validation failed (wrong mint or decimals)
12	`InvalidVault`	Vault doesn't match market
13	`InvalidPDA`	Account doesn't match derived PDA
14	`InvalidAccountOwner`	Account not owned by program
15	`InvalidTokenProgram`	Wrong token program passed
16	`InvalidTokenAccountOwner`	Token account owner mismatch

Input Validation Errors (17-20)#

Code	Name	Description
17	`ZeroAmount`	Amount parameter is 0
18	`ZeroScaledAmount`	Scaled amount rounds to zero
19	`InvalidScaleFactor`	Scale factor is 0 (invalid market state)
20	`InvalidTimestamp`	Timestamp ordering violated

Balance/Capacity Errors (21-27)#

Code	Name	Description
21	`InsufficientBalance`	Token account balance too low
22	`InsufficientScaledBalance`	Scaled amount exceeds balance
23	`NoBalance`	Lender has no scaled balance
24	`ZeroPayout`	Vault empty (no payout available)
25	`CapExceeded`	Deposit exceeds max_total_supply
26	`BorrowAmountTooHigh`	Exceeds available vault funds
27	`GlobalCapacityExceeded`	Exceeds borrower's max_borrow_capacity

Market State Errors (28-35)#

Code	Name	Description
28	`MarketMatured`	Operation not allowed after maturity
29	`NotMatured`	Withdrawal before maturity
30	`NotSettled`	Market not yet settled
31	`SettlementNotImproved`	New settlement factor not > current
32	`SettlementGracePeriod`	Grace period not elapsed before first settlement-triggering withdrawal or force-close (5 min)
33	`SettlementNotComplete`	settlement_factor == 0
34	`PositionNotEmpty`	Lender position cannot be closed
35	`RepaymentExceedsDebt`	Repayment exceeds current debt

Fee/Withdrawal Errors (36-40)#

Code	Name	Description
36	`NoFeesToCollect`	No accrued protocol fees
37	`FeeCollectionDuringDistress`	Fee collection blocked during distress
38	`LendersPendingWithdrawals`	Fee collection blocked (lenders pending)
39	`FeesNotCollected`	Protocol fees not collected yet
40	`NoExcessToWithdraw`	No excess funds in vault

Operational Errors (41-43)#

Code	Name	Description
41	`MathOverflow`	Arithmetic overflow/underflow
42	`PayoutBelowMinimum`	Payout below slippage minimum
43	`NoHaircutToClaim`	Lender has no haircut claim to recover

Common Scenarios#

Deposit Errors#

Code	Name	When It Occurs
17	ZeroAmount	Deposit amount is 0
18	ZeroScaledAmount	Deposit too small (rounds to 0 shares)
25	CapExceeded	Deposit would exceed max_total_supply
28	MarketMatured	Trying to deposit after maturity

Withdrawal Errors#

Code	Name	When It Occurs
23	NoBalance	Position has zero shares
22	InsufficientScaledBalance	Withdrawing more than owned
24	ZeroPayout	Vault is empty
29	NotMatured	Trying to withdraw before maturity
32	SettlementGracePeriod	Still in 5-minute grace period before first settlement-triggering withdrawal or force-close
42	PayoutBelowMinimum	Payout less than specified minimum

Borrow Errors#

Code	Name	When It Occurs
26	BorrowAmountTooHigh	Trying to borrow more than vault holds
27	GlobalCapacityExceeded	Would exceed borrower's whitelist capacity

Repay / RepayInterest Errors#

Code	Name	When It Occurs
17	ZeroAmount	Repay/repay-interest amount is 0
11	InvalidMint	Payer token account mint does not match market mint
35	RepaymentExceedsDebt	Repay amount exceeds current principal debt (Repay only)
8	ProtocolPaused	Protocol is paused

Fee Collection Errors#

Code	Name	When It Occurs
8	ProtocolPaused	Protocol is paused
36	NoFeesToCollect	No fees have accrued
37	FeeCollectionDuringDistress	Settlement factor < WAD (market underfunded)
38	LendersPendingWithdrawals	Lenders still have pending withdrawals

User-Friendly Messages#

Error	Message
MarketMatured	"This market has ended. You cannot deposit."
CapExceeded	"This market is full. Try a smaller amount."
NotMatured	"You can't withdraw yet. Wait until the maturity date."
SettlementGracePeriod	"Please wait 5 minutes after maturity before the first settlement-triggering withdrawal or force-close."
ProtocolPaused	"The protocol is temporarily paused."
PayoutBelowMinimum	"Payout is below your specified minimum. Adjust slippage tolerance."

Handling Errors in Code#

import { parseCoalescefiError, CoalescefiErrorCode } from '@coalescefi/sdk';

try {
  await sendTransaction(tx);
} catch (error) {
  const programError = parseCoalescefiError(error);
  if (programError) {
    console.error(`Error: ${programError.codeName} (${programError.code})`);
    console.error(`Message: ${programError.message}`);
  }
}