Search across all documentation pages
A transaction that simulates cleanly can still never confirm: leaders skip it during congestion, blockhashes expire, or fee bids lose the priority auction. Production triage separates execution failure from inclusion failure before you change program logic.
Quick-reference recipe card - copy-paste ready.
import {
createSolanaRpc,
createSolanaRpcSubscriptions,
pipe,
createTransactionMessage,
setTransactionMessageFeePayer,
setTransactionMessageLifetimeUsingBlockhash,
appendTransactionMessageInstructions,
signTransactionMessageWithSigners,
getSignatureFromTransaction,
} from "@solana/kit";
import {
getSetComputeUnitLimitInstruction,
getSetComputeUnitPriceInstruction,
} from "@solana-program/compute-budget";
// 1. Fresh blockhash 2. Compute budget ix 3. send + subscribeWhen to reach for this:
import { createSolanaRpc, createSolanaRpcSubscriptions } from "@solana/kit";
const rpc = createSolanaRpc(process.env.RPC_URL!);
const subs = createSolanaRpcSubscriptions(process.env.WS_URL!);
async function sendWithLandingWatch(wireBase64: string, signature: string) {
await rpc.sendTransaction(wireBase64, {
encoding: "base64",
skipPreflight: false,
maxRetries: 0,
preflightCommitment: "confirmed",
}).send();
const started = Date.now();
const sub = await subs.signatureNotifications(signature, { commitment: "confirmed" });
for await (const note of sub) {
if (note.value.err) throw new Error(`On-chain err: ${JSON.stringify(note.value.err)}`);
return { landedMs: Date.now() - started, slot: note.context.slot };
}
throw new Error("Subscription ended without confirmation");
}What this demonstrates:
maxRetries: 0 so your app controls retry policy with fresh blockhashessignatureNotifications instead of polling getSignatureStatuseserr separately from never landingset_compute_unit_price) bids micro-lamports per CU; higher bids tend to land first under load.| Signal | Likely cause | Mitigation |
|---|---|---|
| No signature in explorer | RPC never forwarded | Secondary provider, check 429 rate limits |
| Signature exists, no confirmation | Dropped / outbid | Raise priority fee, bundle via Jito |
BlockhashNotFound on resend | Stale lifetime | Fetch new blockhash, re-sign |
| Confirmed then rolled back | Rare fork; usually wrong commitment read | Wait for confirmed or finalized |
// Fetch recent prioritization fees for your program accounts
const fees = await rpc.getRecentPrioritizationFees({
lockedWritableAccounts: [programId],
}).send();
const p75 = fees.value.map((f) => f.prioritizationFee).sort((a, b) => a - b)[
Math.floor(fees.value.length * 0.75)
] ?? 1;getRecentPrioritizationFees.processed for UX - Forks can unwind processed. Fix: Show success at confirmed; settle money at finalized if needed.maxRetries: 0 on send.| Alternative | Use When | Don't Use When |
|---|---|---|
| Jito bundles | Must land atomically with tip | Simple low-value transfers |
| Private RPC / SWQoS | Production dApp baseline | Local development only |
| Lower commitment UX | Read-only dashboards | Payment confirmation |
| Transaction queue service | Backend batching with fee policy | Fully client-side wallets |
Usually no. Inclusion failures are economic and network-scheduling problems unless simulation also fails.
Roughly 60-90 seconds (150 slots). Always fetch a fresh one before resubmit.
Only on trusted server paths with separate simulation. Skipping preflight increases on-chain failure rate.
Start at the p75 of getRecentPrioritizationFees for your writable accounts; tune from landing metrics.
Devnet has low contention. Mainnet fee markets and leader scheduling dominate.
They reduce tx size, improving propagation and fit in blocks - especially for complex DeFi routes.
Timeout on signatureNotifications; compare against getSignatureStatuses on a second RPC.
Yes - duplicate sends of identical wire bytes are idempotent until expiry. After expiry you need a new signature.
Stake-weighted QoS gives staked-connection RPC providers better forwarding to leaders - common in paid tiers.
High-contention mints, arbitrage, or any flow where atomic landing justifies a tip.
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.
Reviewed by Chris St. John·Last updated Jul 16, 2026