Skip to main content

SDK Troubleshooting

This page maps common integration failures to likely causes in the canonical OmegaX model.

Start here if

Use this page when a builder call, simulation, broadcast, read, PDA derivation, claim transition, or reserve calculation is failing and you need the fastest likely cause.

Fast triage​

CheckWhy it matters
Node version is >=20The SDK expects the current runtime baseline.
Runtime uses ESM importsThe package is ESM-only.
programId and RPC cluster matchMismatches look like account, discriminator, or missing-surface failures.
Smallest failing build...Tx(...) reproducesSmaller payloads make simulation logs useful.
Payload, signature, and logs are preservedRetries can erase the only evidence that explains the failure.

Common transaction failures​

missing_fee_payer or missing_required_signature​

Cause:

  • The built transaction was not signed by the required authority.

Fix:

  • Ensure the fee payer and the required signer both sign before serialization.

rpc_timeout​

Cause:

  • Confirmation took too long or the blockhash expired.

Fix:

  • Fetch a fresh blockhash and retry.

network_error​

Cause:

  • RPC transport failed before the transaction reached a terminal state.

Fix:

  • Retry against a healthy endpoint and preserve the failing payload and logs.

Common claim and reserve failures​

protocol_paused​

Cause:

  • A protocol or scoped control is blocking the flow.

Fix:

  • Inspect governance, reserve-domain, health-plan, and capital-class controls before retrying.

claim_intake_paused​

Cause:

  • Claim intake is paused for the relevant scope.

Fix:

  • Resume intake or route the case through the correct plan and series.

not_eligible​

Cause:

  • The member position is not currently eligible.

Fix:

  • Inspect fetchMemberPosition(...) and describeEligibilityStatus(...).

funding_exhausted​

Cause:

  • The relevant funding line does not have enough free capital.

Fix:

  • Inspect fetchFundingLineLedger(...), fetchPlanReserveLedger(...), and recomputeReserveBalanceSheet(...).

allocation_frozen​

Cause:

  • Allocation controls are in freeze or deallocation-only mode.

Fix:

  • Check allocation and capital-class controls before attempting new utilization.

queue_only​

Cause:

  • A capital surface is operating in queue-only mode.

Fix:

  • Use the redemption queue flow instead of expecting immediate redemption.

invalid_claim_state​

Cause:

  • The claim case or obligation is not in a state that permits the requested transition.

Fix:

  • Inspect fetchClaimCase(...) or fetchObligation(...) and only apply valid state transitions.

Claim attestation schema errors​

Cause:

  • Claim-case attestations require a valid schema hash and an oracle profile that supports the selected schema.

Fix:

  • Verify the target outcome schema exists, the schema hash is the one the claim flow expects, and the oracle profile is configured for that schema before calling buildAttestClaimCaseTx(...).

Reader and PDA issues​

account discriminator mismatch for ...​

Cause:

  • You decoded the wrong address for that account type.

Fix:

  • Re-derive the address with the canonical PDA helper and verify cluster and programId.

seed id must be 1..32 UTF-8 bytes​

Cause:

  • A plan, series, funding line, pool, class, or obligation identifier exceeds PDA seed limits.

Fix:

  • Keep IDs within the canonical seed boundary and validate them before building.

Capital and reserve issues​

Capital subscriptions fail unexpectedly​

Cause:

  • The capital class may be paused, restricted, or credential gating may be missing.

Fix:

  • Inspect fetchCapitalClass(...) and describeCapitalRestriction(...).

Redemptions do not process​

Cause:

  • Lockup, queue-only controls, or insufficient redeemable capital can block exit.

Fix:

  • Inspect fetchLPPosition(...), fetchPoolClassLedger(...), and fetchDomainAssetLedger(...).
  • Recompute the reserve sheet with recomputeReserveBalanceSheet(...).

Cause:

  • You may be reading gross vault balance instead of attributed ledger state.

Fix:

  • Treat free capital as ledger-derived, not raw token balance.
  • Use buildSponsorReadModel(...) or buildCapitalReadModel(...) for higher-level views.

If issues persist​

Escalation packet

Before asking for help, keep the smallest reproducing builder call, the SDK version, network target, transaction signature if one exists, and the simulation logs. That set is usually enough to separate SDK usage, RPC transport, and protocol-state issues.

  • Capture the transaction signature.
  • Preserve simulation logs.
  • Record the SDK version and network target.
  • Reduce the failure to the smallest build...Tx(...) call that still reproduces the issue.

Next read​

Download PDF