Skip to main content

SDK Troubleshooting

Use this page to map common @omegax/protocol-sdk integration failures to likely causes and fixes in the canonical OmegaX model.

Fast triage​

  1. Confirm Node version is >=20.
  2. Confirm your runtime is using ESM imports.
  3. Confirm programId and RPC cluster match the deployment you expect.
  4. Confirm settlement-sensitive flows use createSafeProtocolClient(...) unless you are intentionally testing raw protocol builders.
  5. Run the no-signature smoke:
npx @omegax/protocol-sdk doctor
  1. If your application has its own read-only smoke, run it after doctor. A useful smoke imports the SDK, creates a safe client, and lists the public instruction and account names without requiring a funded signer.

If doctor passes but your app still fails, reduce the issue to the smallest SDK import, client creation, account read, or build...Tx(...) call that reproduces the behavior.

Typed SDK errors​

Public failure paths that app builders can act on now throw typed errors from @omegax/protocol-sdk/errors. Branch on instanceof or the stable code field instead of parsing message text.

Common codes:

  • OMEGAX_CONFIG_ERROR
  • OMEGAX_INVALID_PUBLIC_KEY
  • OMEGAX_PROGRAM_MISMATCH
  • OMEGAX_ACCOUNT_NOT_FOUND
  • OMEGAX_ACCOUNT_OWNER_MISMATCH
  • OMEGAX_TOKEN_ACCOUNT_PREFLIGHT
  • OMEGAX_INSTRUCTION_BUILD
  • OMEGAX_TRANSACTION_DECODE
  • OMEGAX_RPC_ERROR

See SDK Error Catalog for causes, fixes, and retry guidance.

Install warning for uuid​

Some Solana dependency trees still print an install warning for uuid@8.3.2 when a consumer project installs the packed SDK or a scaffolded template. Treat that warning as non-blocking for SDK integration.

If your package manager supports dependency audits, run the audit that your application uses for release. Treat SDK integration warnings separately from transaction-safety checks.

Transaction and submission issues​

Missing fee payer or required signature​

Cause:

  • The built transaction returned missing_fee_payer or missing_required_signature because it was not signed by the required signer.

Fix:

  • Ensure your fee payer signs before serialization.
  • Align the signer with the authority required by the instruction scope.

Simulation returns unverified signature​

Cause:

  • The simulation returned signatureVerified: false because the caller disabled sigVerify, or explicitly allowed fallback after the RPC rejected signature-verifying simulation arguments.

Fix:

  • Treat the simulation as preflight-only.
  • Re-sign and simulate with sigVerify: true.
  • For claim or intake flows, call validateSignedClaimTx(...) before trusting the submitted transaction, and always pass the exact server-stored expectedUnsignedTxBase64 transaction that the user was supposed to sign.

RPC timeout​

Cause:

  • Confirmation took too long or the blockhash expired.

Fix:

  • Fetch a fresh blockhash with getRecentBlockhash().
  • Rebuild, re-sign, and resubmit the transaction.

Network error​

Cause:

  • RPC transport or network connectivity interrupted submission.

Fix:

  • Retry against a healthy RPC endpoint.
  • Record simulation logs so you can distinguish transport failures from program failures.

Canonical claim and obligation failures​

These are normalized by normalizeClaimSimulationFailure(...) and normalizeClaimRpcFailure(...).

Protocol paused​

Cause:

  • A protocol or plan-level control is blocking the claim flow.

Fix:

  • Inspect governance, reserve-domain, health-plan, or capital-class pause state 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 MemberPosition is not eligible for the requested claim or payout.

Fix:

  • Verify fetchMemberPosition(...) and describeEligibilityStatus(...).

Funding exhausted​

Cause:

  • The applicable funding line or reserve scope does not have enough free capital.

Fix:

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

Allocation frozen​

Cause:

  • Allocation controls are in deallocation-only or freeze 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 buildRequestRedemptionTx(...) and wait for buildProcessRedemptionQueueTx(...) rather than expecting immediate exit.

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.

Builder and PDA issues​

Seed ID length​

Cause:

  • A plan, series, funding-line, pool, class, or obligation identifier triggered seed id must be 1..32 UTF-8 bytes because it exceeds PDA seed limits.

Fix:

  • Validate identifiers with isSeedIdSafe(...) or assertSeedId(...).

Account discriminator mismatch​

Cause:

  • The address does not point to the account type you tried to decode.

Fix:

  • Re-derive the address with the canonical PDA helper.
  • Confirm the programId and cluster are correct.
  • Use fetch...(...) readers instead of ad hoc decoding where possible.

Package subpath not exported​

Cause:

  • Your import returned ERR_PACKAGE_PATH_NOT_EXPORTED because the subpath is not part of the public export map.

Fix:

  • Use one of the documented public subpaths such as @omegax/protocol-sdk/protocol_models, @omegax/protocol-sdk/protocol_seeds, or @omegax/protocol-sdk/transactions.
  • Check SDK API Reference and Release Notes before using a newly mentioned package subpath.

Reserve and capital issues​

Capital subscriptions fail unexpectedly​

Cause:

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

Fix:

  • Inspect fetchCapitalClass(...).
  • Check describeCapitalRestriction(...).

Redemptions do not process​

Cause:

  • The position may still be locked, queue-only controls may apply, or redeemable capital may be insufficient.

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.

Version and surface mismatch​

If a documented helper, account, or subpath is missing in your installed package:

  1. Confirm the installed package version with your package manager.
  2. Compare it with SDK Release Notes.
  3. Reinstall or upgrade @omegax/protocol-sdk if your lockfile is still pinned to an older release.
  4. Re-run npx @omegax/protocol-sdk doctor.

If the mismatch persists, capture the SDK version, cluster, programId, and the smallest code sample that reproduces the issue.

If issues persist​

  • Capture the transaction signature.
  • Preserve simulation logs.
  • Record SDK version, cluster, programId, and the package subpath or helper you used.
  • Reduce the failure to the smallest build...Tx(...) call that still reproduces the issue.