Custos docs

Reference

Troubleshooting

Every custom error the contracts raise, what it means and what to do about it, grouped by contract. Then the limits we know about.

Common situations#

  • The keeper stopped. Usually the reserve can't cover the next run's gas hold (gasLimit × gasPrice), so the scheduled run failed INSUFFICIENT_PAYER_BALANCE and nothing booked the next one. Check canPayNextRun(), fund() the market, then call revive() once the tick is overdue (nextRunAt + 2 × interval). /keeper has both buttons; see The keeper.
  • The market is close-only. The price is Stale or Deviated: opens, manual liquidations and refuels refuse it, and the keeper skips the sweep. Wait for the feeds; PriceGuard.read() says which feed is old or how far apart they are.
  • A deposit reverts with LiquidityPool__NoPrice. Deposits and withdrawals pause while positions are open and the price isn't Ok, so shares are never priced at a bad price. Wait for the feeds.
  • LiquidityPool__HtsFailed with rc 184 (TOKEN_NOT_ASSOCIATED_TO_ACCOUNT). The receiver isn't associated with cUSDC-LP: call associate() on the share token (the Pool page does it for you).

Keeper#

Error (selector)MeansFix
ScheduledKeeper__OnlyNetwork0xe3093212Someone other than the Schedule Service called tick()Nothing to fix: only the network ticks. To restart a stopped chain use revive()
ScheduledKeeper__TooEarly(nextRunAt)0x6f69966dA tick arrived more than 5 s before nextRunAt, or no tick is booked (nextRunAt 0)Wait; if nextRunAt is 0, call revive()
ScheduledKeeper__NotOverdue(overdueAt)0x0681ef5drevive() while the chain is still healthyRevive only after overdueAt = nextRunAt + 2 × interval
ScheduledKeeper__InvalidConfig0xc13e0c4eInterval 0, gas limit ≤ 1.6M, or gas price > 1,000,000Use a gas limit above 1,600,000
ScheduledKeeper__Reentrant / OnlySelfInternal guardsDon't call runWork() or re-enter tick()/revive() from _work()

PriceGuard#

Error (selector)MeansFix
PriceGuard__NotOk(status)0x9bf2faf0Price is Stale (1) or Deviated (2): opens, manual liquidations and refuels refuse itWait for the feeds; check read() for which feed is old or how far apart they are
PriceGuard__InvalidConfig0x9625e495Zero feed address, Chainlink decimals > 18, staleness 0 or > 1 day, deviation 0 or > 2,000 bpsFix the market's config (its entry in markets.json)

PerpMarket#

Error (selector)MeansFix
PerpMarket__BelowMinCollateral(min)0x3fe7dc18Collateral (or what openWithHbar's swap returned) is under minCollateralPut up more; 1 USDC on the testnet deploy (~0.45 ℏ at SaucerSwap testnet's rate)
PerpMarket__InvalidLeverage0xca94e446Leverage 0 or > 50, or the open fee would eat the collateralUse 1–50
PerpMarket__OpenInterestCap(cap)0xf5de5219The pool can't back a position this bigSmaller size, or more pool liquidity
PerpMarket__PositionExists / NoPositionOne position per accountClose first / open first
PerpMarket__HoldTime(closeableAt)0x52765821Closing within 300 s of openingWait until closeableAt
PerpMarket__NoPrice0x5cda1032Neither feed is fresh (younger than maxStaleness), so there's no price to close atWait for a feed to push again
PerpMarket__NotLiquidatable0x2103964cThe position isn't underwater at the current price—
PerpMarket__SwapDisabled0x0002a87dDeployed without a SaucerSwap routerUse open / close with USDC
PerpMarket__OnlyKeeper0xeee4b657refuel() called by someone elseOnly the keeper's tick refuels
PerpMarket__ReserveNotLow / NothingToSpendRefuel not needed / the pool has no free USDC—

LiquidityPool#

Error (selector)MeansFix
LiquidityPool__NoPrice0x40c172d5Deposits and withdrawals pause while positions are open and the price isn't OkWait for the feeds
LiquidityPool__ExceedsMax(max)0x139fca36More than you hold, or more than the pool can release (it keeps 2 × open interest)Use maxRedeem / maxWithdraw
LiquidityPool__TooFewShares(shares)0x8811e726First deposit must exceed the 1,000 dead shares (0.001 USDC)Deposit more
LiquidityPool__NoShareToken / ShareTokenExistscreateShareToken() not called yet / already calledRun yarn custos:deploy:testnet (it creates it)
LiquidityPool__HtsFailed(rc)0x0c9ebca3The Token Service refused a mint/burn/transfer; rc is the Hedera response codeUsually the receiver isn't associated with cUSDC-LP (rc 184 TOKEN_NOT_ASSOCIATED_TO_ACCOUNT): call associate() on the share token
LiquidityPool__OnlyMarket / ExceedsFreeAssetsOnly the market draws on the pool, and only from USDC no position needs—

SaucerSwap and Hedera#

ErrorMeansFix
INSUFFICIENT_PAYER_BALANCEA scheduled run failed to start: the reserve can't cover gasLimit × gasPrice. The failed attempt still costs 0.018 ℏfund() the market (check canPayNextRun()), then revive() once overdue
"slippage" (SaucerSwap)The swap would return less than your minimum (or, for refuel, less than 97% of the oracle price)Re-quote with quoteHbarToUsdc / quoteUsdcToHbar; on testnet refuels fail this way by design (Learned on Hedera, item 8)
CONTRACT_EXECUTION_EXCEPTIONThe relay rejects a deploy: the contract is over 24 KBKeep the optimizer on (foundry.toml)

Honest limits#

  • Testnet refuels fail closed. SaucerSwap testnet's USDC pool is ~22x off the oracle, so the keeper is funded by hand on testnet. Self-refuel is proven by tests at sane prices.
  • The keeper costs real HBAR. About 1.4 ℏ per run, ~65 ℏ a day at a 30 min interval. When the reserve can't cover the next run's gas hold, the chain stops until someone funds and revives it.
  • Push oracles lag. Chainlink and Supra update on deviation or heartbeat, so the market trades on a price that can be minutes old, and a 50x position can be hit by oracle lag. The 300 s minimum hold and the 0.1% fees blunt it; they don't remove it.
  • Liquidation keeps the remainder. A liquidated position's leftover equity (up to 1% of notional) goes to the pool, not back to the trader.
  • The pool's value ignores the per-position gain cap and loss floor. Exact until a position is past +100% or below zero equity; liquidation keeps positions away from the floor.
  • LPs are locked while prices are bad. Deposits and withdrawals pause while positions are open and the price isn't Ok, so shares are never priced at a bad price.
  • One position per account, one market per deployment. More markets are more deployments from markets.json; the app shows the default market.
  • Funding is linear and simple (skew / pool assets); there's no price impact and no borrow fee.
  • The keeper's HBAR can't be withdrawn. It can only pay for network runs. Redeploying leaves the old reserve behind.
  • The owner can tune, not take. PerpMarket's owner can only correct the gas-price estimate; PriceGuard's owner can only change staleness/deviation within hard bounds; the pool's owner links the market and creates the share token once each. No one can move user funds.
  • The live testnet deploy predates the stale-close fix. A review on 2026-10-03 found that, with one feed down, closePrice() used the other feed without checking its age, so a trader could close at an old price that favoured them. The source now settles a close only at a feed younger than maxStaleness (and waits if neither is), and treats a feed timestamp more than 5 minutes in the future as stale (PriceGuard.MAX_FUTURE_SKEW); regression tests replay the attack. The contracts deployed on 2026-10-02 still have the old behaviour. On testnet the exposure needs Chainlink to stop answering while Supra is stale at a favourable price, and is capped by each position's gain cap; the live deploy was kept rather than strand its funded keeper reserve and its network-run proofs. A new deploy from this source has the fix.
  • Testnet assets. USDC 0.0.5449 is SaucerSwap's testnet token.
  • Local chain is for trading and the pool only. yarn foundry:chain + yarn foundry:deploy runs everything on mocks with stand-ins for the two system contracts; the keeper books ticks but nothing runs them, and the mock feeds go Stale 2 h after deploy (move them with MockAggregator.set / MockSupra.set from /debug).