Skip to main content

SDK Troubleshooting

Use this page to quickly diagnose common integration failures.

Fast checks​

  • Node.js version is >=20
  • Project uses ESM ("type": "module")
  • Correct programId for target environment
  • Transaction built with fresh recent blockhash

Signature and message errors​

invalid_transaction_base64​

Meaning:

  • Signed payload passed to validation is malformed.

Fix:

  • Base64-encode raw bytes from tx.serialize().

missing_fee_payer / missing_required_signature​

Meaning:

  • Required signer did not sign the transaction.

Fix:

  • Ensure fee payer and required signer identities are aligned before serialization.

required_signer_mismatch​

Meaning:

  • Signed tx fee payer is different from expected signer.

Fix:

  • Match signer wallet with protocol actor identity (claimant/delegate/oracle as appropriate).

intent_message_mismatch​

Meaning:

  • Signed tx message bytes no longer match prepared unsigned intent.

Fix:

  • Do not mutate tx fields after creating unsigned claim intent.

Builder validation errors​

poolId exceeds 32 UTF-8 bytes​

Fix:

  • Keep poolId at or below 32 UTF-8 bytes.

supported schema key hashes cannot exceed 16​

Fix:

  • Limit oracle schema hash lists to max 16 entries per call.

protocolFeeBps must be an integer between 0 and 10000​

Fix:

  • Use integer fee values in [0, 10000].

poolAssetVault, poolVaultTokenAccount, and recipientTokenAccount must be provided together​

Fix:

  • Provide all SPL payout option accounts together, or omit all for non-SPL payout flow.

Reader decode failures​

account discriminator mismatch for ...​

Usually means:

  • wrong account type or address
  • wrong cluster/program pairing
  • protocol/SDK version mismatch

Fix:

  • Recompute PDA with SDK seed helpers and verify the target account type.

RPC simulation and broadcast failures​

simulation_failed_insufficient_funds​

Fix:

  • Ensure pool and payer balances are sufficient for payout path.

simulation_failed_pool_paused​

Fix:

  • Confirm pool/protocol status allows target action.

simulation_failed_membership_invalid​

Fix:

  • Confirm member is enrolled and active for target pool.

rpc_timeout​

Fix:

  • Refresh blockhash and retry; evaluate RPC latency/availability.

rpc_rejected​

Fix:

  • Simulate first, inspect logs, then retry with corrected accounts/signatures.
Download PDF