Why Transactions Fail to Land
Transactions fail to land when blockhashes expire, compute budgets are exhausted, priority fees are too low, or RPC submission never reaches a leader.
Recipe
Quick-reference recipe card - copy-paste ready.
solana confirm -v <SIGNATURE>
solana transaction <SIGNATURE> --output json-compact | jq '.meta.err, .meta.logMessages'const sim = await rpc.simulateTransaction(wireTx, { sigVerify: false }).send();
console.log(sim.value.err, sim.value.unitsConsumed);When to reach for this:
- Users report "stuck" pending transactions.
- Simulation succeeds but mainnet send never confirms.
- Intermittent failures during NFT mints or airdrops.
- Post-mortem after incident spikes.
Working Example
import { createSolanaRpc } from "@solana/kit";
const rpc = createSolanaRpc(process.env.RPC_URL!);
const status = await rpc.getSignatureStatuses([signature]).send();
const value = status.value[0];
console.log({
confirmationStatus: value?.confirmationStatus,
err: value?.err,
slot: value?.slot,
});
const tx = await rpc
.getTransaction(signature, { encoding: "json", maxSupportedTransactionVersion: 0 })
.send();
console.log("landed err:", tx?.value?.meta?.err);
console.log("logs tail:", tx?.value?.meta?.logMessages?.slice(-5));What this demonstrates:
getSignatureStatusesshows if signature is unknown (dropped) vs failed vs confirmed.- Landed failed txs include program errors in meta.
- Unknown signature often means never included before blockhash expiry.
Deep Dive
How It Works
- Leaders prioritize transactions by fee and compute price during congestion.
- Recent blockhash in transaction expires after ~150 slots (~60-90s wall clock).
- CU meter stops execution when limit exceeded - transaction fails on-chain.
- RPC may accept
sendTransactionbut validator drops tx if underpriced.
Failure Categories
| Symptom | Likely cause | Fix direction |
|---|---|---|
| Signature not found | Dropped / expired blockhash | Rebuild tx, higher priority fee |
| Program error in meta | Logic bug | Fix program or accounts |
| CU exceeded | Limit too low | Raise compute budget |
| Blockhash not found | Too old | Fresh blockhash + retry |
bash Notes
# Check if still valid blockhash age at send time - compare current slot to tx slot in logs
solana slotGotchas
- Assuming RPC OK means landed -
sendTransactionreturns signature before inclusion. Fix: track confirmation status separately. - Zero priority fee on congested mainnet - tx starves in queue. Fix: dynamic fees (Setting Priority Fees).
- Default 200k CU too low - complex txs fail simulation. Fix: estimate CU (Estimating Compute Units).
- Single RPC send - packet loss or bad peer. Fix: rebroadcast with retries (Retries & Blockhash Management).
- Oversized legacy transaction - exceeds packet size. Fix: v0 + ALTs (Address Lookup Tables in Practice).
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Jito bundles | High contention landing | Simple devnet tests |
| Durable nonce | Long-lived signing flow | Normal fresh blockhash txs |
| Private RPC send | Better propagation | Cost-sensitive MVP |
| Lower traffic window | Ops mitigation | User-facing real-time UX |
FAQs
Does simulation failure guarantee no landing?
Usually - but race conditions rare; treat simulation as strong signal.
Why success in devnet but not mainnet?
Mainnet congestion and higher account lock contention - fees and CU differ.
What is blockhash expiry?
Transaction recent blockhash must be in recent blockhash queue known to validators - stale hashes reject inclusion.
Can a tx land then fail?
Yes - included in block with meta.err program failure; you still pay base fee.
How do I detect dropped txs?
getSignatureStatuses returns null for unknown signature after waiting period.
Do priority fees guarantee landing?
No - they improve probability under contention; program errors and CU still fail.
Role of skipPreflight?
false catches errors early; true faster send but more dropped bad txs.
Versioned transaction relevance?
v0 enables ALTs to fit large account lists - legacy size limits cause silent drops.
Jito vs priority fee?
Jito tips validators on bundle path; priority fees are native compute unit price - complementary.
Where is full landing pipeline?
Related
- Estimating Compute Units - CU failures
- Setting Priority Fees - fee strategy
- Retries & Blockhash Management - expiry handling
- Priority Fee & Simulation APIs - RPC tools
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.