Troubleshooting
Grouped by what you are actually looking at when it goes wrong. Start with the activity feed, find the stage that did not report, then find it below.
Before anything else
- 01
Read the activity feed
It records each stage in order. The last stage that reported tells you where the problem is, and that is usually the whole diagnosis.
- 02
Check nothing was applied
A bundle either lands or does not. If it did not land, no token was created and no buy happened. There is nothing to clean up.
- 03
Do not send anything manually
Improvising a fix while a retry is in flight is how people buy twice. Let the policy finish first.
The bundle did not land
Submitted, then nothing
CauseThe bundle reached the block engine but did not win a slot. Inclusion is competitive and the tip did not clear what others were paying.
FixRaise the tip and resubmit. Rebuild against fresh state rather than resending the same assembled bundle, because the state it was built for has moved.
Rejected during assembly
CauseThe launch does not pack into a valid bundle. Usually too many wallets for the instruction set you configured.
FixReduce the wallet count, or move some wallets to Reserve so they are not in the launch bundle, and simulate again.
One wallet failed and took the bundle with it
CauseA funded wallet was short of what its transaction actually cost once rent and fees were counted. A failed transaction fails the whole bundle by design.
FixTop up the wallet the feed names, leave a margin above the quoted amount rather than matching it exactly, and simulate again.
Landed, but the fills are wrong
CauseThe chain moved between the simulation and the execution. Another buyer, a pool change, or simply time passing.
FixNothing to fix on this launch. Next time simulate immediately before executing, and narrow your slippage if the divergence was larger than you can accept.
The expensive mistake
Never manually buy while a retry is still running. If the bundle lands afterwards you have bought twice, at a worse price, from wallets you now have to reconcile.
Simulation failed
Insufficient funds on a wallet
CauseThe wallet holds enough for the buy but not for the buy plus its fees plus the rent for the accounts it will create.
FixFund above the quoted figure rather than exactly at it. The pre-flight names the wallets that are short.
Slippage exceeded
CauseA buy would fill outside your tolerance. Usually the total buy size is large against available liquidity, so the later wallets in the order are the ones that break.
FixReduce the total, widen the slippage tolerance, or reorder so the largest buys are earlier. Widening slippage means accepting a worse price, so read the fills before you do it.
Invalid mint address
CauseThe pasted address is not a mint, or it is a mint on a different cluster than the one you are targeting.
FixCheck the address character by character and confirm the terminal is pointed at the right cluster. A devnet mint will not resolve on mainnet.
Metadata will not attach
CauseThe image or metadata upload did not complete, so the create instruction has nothing to point at.
FixRe-upload the image. If it keeps failing, try a smaller file and a standard format before assuming the problem is elsewhere.
It passed an hour ago and fails now
CauseSimulation reads current chain state. Everything moves.
FixThis is the system working. Fix what it flags and rerun. A stale pass is not evidence of anything.
The wallet will not connect
Nothing happens when you click connect
CauseThe wallet extension is locked, or a popup was blocked, or another dapp still holds a pending request.
FixUnlock the wallet, allow popups for the site, close other dapp tabs, then try again.
Connected, but the terminal shows no address
CauseThe wallet approved a different account than the one selected, or the connection was granted to a different site origin.
FixDisconnect from inside the wallet, switch to the account you intend to use, and reconnect from the terminal.
Two wallets fight over the connection
CauseMore than one wallet extension is claiming the same provider, which happens when several are installed and all set to be the default.
FixDisable the ones you are not using for this session, or set exactly one as default and reload.
The signature request never appears
CauseThe popup opened behind the browser window, or the wallet is waiting on an earlier request you did not dismiss.
FixOpen the wallet directly and look for a queued request. Clear it, then retry the action.
A balance is not showing
You funded a wallet and it still reads empty
CauseThe transfer has not confirmed yet, or the view is reading a cached response.
FixWait for confirmation, then refresh the vault. If the explorer shows the balance and the terminal does not, the terminal is stale rather than wrong.
Tokens do not appear after a launch
CauseThe wallet has not been told about the token account yet. New tokens frequently need a manual refresh in the wallet before they show.
FixRefresh the wallet, or add the mint address manually. Check the token account on an explorer to confirm the balance is really there.
The sweep returned less than expected
CauseRent from accounts that could not be closed, plus the fees the sweep transactions themselves cost.
FixThis is normal. Compare against the accounts that remained open rather than against the total you funded.
Everything reads zero across every wallet
CauseThe terminal is pointed at the wrong cluster. Mainnet balances do not exist on devnet and the reverse is also true.
FixCheck the cluster setting first. It explains this symptom more often than anything else does.
Still stuck
Collect three things before asking for help: what the activity feed shows, the last stage that reported, and what the simulation said the last time you ran it. That is almost always enough to identify the problem without anyone guessing.
Never include this
No support conversation needs your private key or your seed phrase. Anyone asking for either is not helping you.
FAQ
Short answers to the questions that come up most.