1---
2title: Common Gotchas
3description: Common type errors and runtime pitfalls with @solana/kit and their fixes, including signer types, lifetime assertions, plugin ordering, and account existence.
4---
5 
6# Solana Kit Gotchas
7 
8Common type errors and runtime pitfalls with their fixes.
9 
10## Plugin Client Gotchas
11 
12### Plugin Ordering — Type Error
13 
14**Cause:** Plugins installed before their dependencies. `solanaRpc` / `solanaLocalRpc` / `solanaDevnetRpc` / `litesvm` all require a `payer` to be installed first; low-level `rpcTransactionPlanner` / `rpcTransactionPlanExecutor` require `rpc` and `payer`.
15 
16```ts
17// ❌ Type error — solanaRpc requires payer
18createClient()
19  .use(solanaRpc({ rpcUrl: url }))
20  .use(signer(mySigner));
21 
22// ✅ Fix: signer first (sets payer + identity), then RPC bundle
23createClient()
24  .use(signer(mySigner))
25  .use(solanaRpc({ rpcUrl: url }));
26```
27 
28### Forgetting to `await` Async Client
29 
30**Cause:** Some plugins (e.g., `signerFromFile`, `generatedSigner`, `generatedSignerWithSol`) are async, and `.use()` automatically threads the promise through the chain.
31 
32```ts
33// ❌ Runtime error — client is a Promise, not a client
34const client = createClient()
35  .use(signerFromFile('./id.json'))
36  .use(solanaLocalRpc());
37client.sendTransaction([ix]); // TypeError: not a function
38 
39// ✅ Fix: await the client
40const client = await createClient()
41  .use(signerFromFile('./id.json'))
42  .use(solanaLocalRpc());
43await client.sendTransaction([ix]);
44```
45 
46---
47 
48## Type Errors
49 
50### `IInstruction` does not exist
51 
52**Cause:** Using old type name from legacy web3.js.
53 
54```ts
55// ❌ Type error
56import { IInstruction } from '@solana/kit';
57 
58// ✅ Fix: Use Instruction
59import type { Instruction } from '@solana/kit';
60```
61 
62### "Transaction message must be signed"
63 
64**Cause:** Trying to send unsigned message (manual pipeline only).
65 
66```ts
67// ✅ Fix: Assert fully signed
68import { assertTransactionMessageIsFullySigned } from '@solana/transaction-messages';
69assertTransactionMessageIsFullySigned(message);
70```
71 
72### "Missing blockhash lifetime"
73 
74**Cause:** Message missing lifetime before signing/sending (manual pipeline only).
75 
76```ts
77// ✅ Fix: Assert lifetime exists
78import { assertTransactionMessageHasBlockhashLifetime } from '@solana/transaction-messages';
79assertTransactionMessageHasBlockhashLifetime(message);
80```
81 
82### `signAndSendTransactionMessageWithSigners` type error
83 
84**Cause:** Fee payer set as address, not signer.
85 
86```ts
87// ❌ Type error — fee payer is address only
88setTransactionMessageFeePayer(address, message);
89 
90// ✅ Fix: Use signer version
91setTransactionMessageFeePayerSigner(signer, message);
92```
93 
94### Wrong signer type for wallet
95 
96**Cause:** Using `TransactionSigner` for wallet that needs to send.
97 
98```ts
99// Wallets that submit transactions need TransactionSendingSigner
100type TransactionSendingSigner = {
101  signAndSendTransactions(txs): Promise<SignatureBytes[]>;
102};
103```
104 
105### Missing Lifetime Type Assertion
106 
107**Cause:** `sendAndConfirm` requires typed lifetime assertion (manual pipeline only).
108 
109```ts
110// ❌ Type error: Property '"__transactionWithBlockhashLifetime"' is missing
111const signed = await signTransactionMessageWithSigners(message);
112await sendAndConfirm(signed, { commitment: 'confirmed' });
113 
114// ✅ Fix: Assert lifetime + size types
115assertIsTransactionWithBlockhashLifetime(signed);
116assertIsTransactionWithinSizeLimit(signed);
117await sendAndConfirm(signed, { commitment: 'confirmed' });
118```
119 
120### Missing `TransactionWithinSizeLimit`
121 
122**Cause:** Recent Kit versions require size assertion for send factories.
123 
124```ts
125// ✅ Fix: Add size assertion
126import { assertIsTransactionWithinSizeLimit } from '@solana/kit';
127assertIsTransactionWithinSizeLimit(signed);
128```
129 
130### RPC URL String vs Cluster Wrapper
131 
132**Cause:** Using `devnet()`/`mainnet()` wrappers when raw URL string expected.
133 
134```ts
135// ❌ May cause issues
136import { devnet } from '@solana/rpc-types';
137const rpc = createSolanaRpc(devnet('https://my-custom-endpoint.com'));
138 
139// ✅ Simple: use raw URL strings directly
140const rpc = createSolanaRpc('https://api.devnet.solana.com');
141```
142 
143---
144 
145## Runtime Errors
146 
147### "Account does not exist"
148 
149**Cause:** Decoding account that may not exist.
150 
151```ts
152// ❌ Runtime error if account missing
153const account = await fetchEncodedAccount(rpc, address);
154const decoded = decodeAccount(account, decoder);
155 
156// ✅ Fix: Assert existence first
157const account = await fetchEncodedAccount(rpc, address);
158assertAccountExists(account);
159const decoded = decodeAccount(account, decoder);
160```
161 
162### Blockhash expired after CU estimation
163 
164**Cause:** Simulation takes time, blockhash ages out. Only applies to manual pipeline — plugin clients handle this automatically.
165 
166```ts
167// ❌ Blockhash may expire
168let message = pipe(...blockhash...);
169message = await estimateAndUpdateCU(message);
170await signAndSendTransactionMessageWithSigners(message);
171 
172// ✅ Fix: Refresh blockhash AFTER estimation
173let message = pipe(...blockhash...);
174message = await estimateAndUpdateCU(message);
175const { value: freshBlockhash } = await rpc.getLatestBlockhash().send();
176message = setTransactionMessageLifetimeUsingBlockhash(freshBlockhash, message);
177await signAndSendTransactionMessageWithSigners(message);
178```
179 
180### Simulation fails with "account not found"
181 
182**Cause:** Account doesn't exist yet (e.g., PDA not initialized).
183 
184```ts
185const account = await fetchEncodedAccount(rpc, address);
186if (!account.exists) {
187  // Handle missing account — may need to create it first
188}
189```
190 
191---
192 
193## Quick Reference
194 
195| Gotcha | Fix |
196|--------|-----|
197| Plugin ordering type error | Install dependencies before dependents (`signer()` before `solanaRpc`/`litesvm`) |
198| Forgot to `await` async client | `const client = await createClient().use(signerFromFile(...)).use(solanaLocalRpc())` |
199| `IInstruction` doesn't exist | Use `Instruction` from `@solana/kit` |
200| "Transaction message must be signed" | `assertTransactionMessageIsFullySigned(msg)` |
201| "Missing blockhash lifetime" | `assertTransactionMessageHasBlockhashLifetime(msg)` |
202| Blockhash expired after CU estimation | Refresh blockhash AFTER `estimateAndUpdateCU()` |
203| `signAndSendTransactionMessageWithSigners` type error | Use `setTransactionMessageFeePayerSigner` (not address) |
204| Account doesn't exist runtime error | `assertAccountExists(account)` before decode |
205| Wrong signer type for wallet | Use `TransactionSendingSigner` for wallets |
206| Missing lifetime type on send | `assertIsTransactionWithBlockhashLifetime(signed)` |
207| Missing size type on send | `assertIsTransactionWithinSizeLimit(signed)` |
208| Durable nonce send type error | `assertIsTransactionWithDurableNonceLifetime(signed)` |
209| `lifetimeConstraint` lost after deserialize | Re-attach `lifetimeConstraint` metadata manually |
210| RPC URL wrapper issues | Use raw URL strings instead of `devnet()`/`mainnet()` |
211