TLDR:
npm install @solana/web3.js installs v3. Code written for v1 fails on v3, because key and transaction methods are async, numbers are bigint, account data is a Uint8Array, and some methods are removed.
@solana/spl-token, Anchor, and other libraries built on web3.js v1 don’t run on v3. Install @solana/web3.js@1 with them, or move to @solana-program/token.
- On Trader Nodes, pass
wsEndpoint to Connection, because their WSS endpoint is on a separate host.
Which @solana/web3.js version you have
The latest tag of @solana/web3.js on npm is v3, so a plain npm install @solana/web3.js installs v3. Check the installed version with:
Three Solana JavaScript libraries are in use:
@solana/web3.js v1 — the legacy line. It receives critical fixes only.
@solana/web3.js v3 — the current release. It keeps the class-based v1 API, rebuilt on Solana Kit, with breaking changes from v1.
@solana/kit — the functional SDK that v3 is built on. See Solana tooling.
To upgrade code from v1 to v3, follow the official v1 to v3 migration guide.
v3 also changes a default: when you don’t set a commitment, v3 requests confirmed data, while v1 sent no commitment and the node returned finalized data. Set the commitment explicitly if your code depends on one.
Errors from v1 code on web3.js v3
Signature verification failed. Missing signature for public key
In v3, transaction.sign(), transaction.partialSign(), and transaction.serialize() on a legacy Transaction return promises. Without await, the transaction is serialized before the signature is added. Await each call:
Cannot read properties of undefined
In v3, Keypair.generate(), Keypair.fromSecretKey(), and Keypair.fromSeed() return promises, so .publicKey on the result is undefined. Await the call:
@solana/spl-token functions such as createMint fail with the same error on v3, because the library creates keypairs the v1 way. See ERESOLVE when you install @solana/spl-token.
Cannot mix BigInt and other types
In v3, lamports, slots, block heights, fees, and other RPC numbers are bigint, while LAMPORTS_PER_SOL is still a number. Convert one side explicitly:
Comparisons fail silently instead of throwing: a zero balance is 0n, so lamports === 0 is false. Compare with 0n.
Do not know how to serialize a BigInt
JSON.stringify can’t serialize the bigint values in v3 RPC results. Pass a replacer:
X is not a function
v3 removes several v1 methods. The message names the method your code called:
Install errors
npm error ERESOLVE unable to resolve dependency tree
@solana/spl-token declares @solana/web3.js v1 as a peer dependency, so npm can’t add it to a project that already has v3. Choose one of these fixes:
- To keep using
@solana/spl-token, install web3.js v1 with it: npm install @solana/web3.js@1 @solana/spl-token.
- To use web3.js v3, replace
@solana/spl-token with @solana-program/token, or @solana-program/token-2022 for Token-2022 mints. See the official @solana/spl-token migration guide.
Other package managers don’t stop on this conflict. pnpm and Bun install v3 next to @solana/spl-token, and the code then fails with Cannot read properties of undefined. Pin @solana/web3.js@1 with them too.
Installing @solana/spl-token-metadata together with an unpinned @solana/web3.js can loop on ERESOLVE warnings without finishing. Pinning @solana/web3.js@1 in the same command resolves it.
WebSocket subscriptions fail on Trader Nodes
Connection derives its WebSocket URL from the HTTPS endpoint when you don’t pass wsEndpoint: it changes the scheme to wss:// and keeps the host. On Global Nodes, the HTTPS and WSS endpoints share a host, so the derived URL is correct.
On Trader Nodes, the WSS endpoint is on a separate host with a ws- prefix, such as ws-nd-….p2pify.com. The derived URL points at the HTTPS host instead, so subscriptions fail, and sendAndConfirmTransaction times out with TransactionExpiredBlockheightExceededError. Pass both endpoints from the node’s access details:
Passing wsEndpoint works on every node type, and v1 and v3 derive the URL the same way. Trader Nodes are deprecated on December 1, 2026. See Migrate from Trader Nodes.
@solana/kit takes the RPC and subscription endpoints as separate inputs, so it never derives a URL:
See also
Last modified on November 12, 2026