DEV Community

Cover image for Your Node.js Version Will Break Solana (And How to Fix It)
Hauwa Ibrahim
Hauwa Ibrahim

Posted on

Your Node.js Version Will Break Solana (And How to Fix It)

#100daysofsolana #writing #web3 #beginners

The Headline That Would've Saved Me 72 Hours

Let me start with a confession:

I spent three days debugging code that wasn't broken.

The code was fine. The logic was correct. The Solana API was working.

The problem? My Node.js version.

And nobody told me.

So here I am, three days later, writing what I wish someone had written for me.

The Setup: This Should've Been Easy

I'm a developer. Not a blockchain expert. Not a crypto bro. Just web 2 developer curious about web 3.

I wanted to build something simple for my #100DaysOfSolana challenge:

  • Take a Solana address
  • Fetch its balance
  • Display account info
  • Done. 15 minutes. Maybe 30.

I found the code in the Solana tutorials provided:

import { createSolanaRpc, address } from "@solana/kit";

const rpc = createSolanaRpc("https://api.devnet.solana.com");
const targetAddress = address(process.argv[2]);
const { value: balanceLamports } = await rpc.getBalance(targetAddress).send();
console.log(`Balance: ${balanceLamports / 1_000_000_000} SOL`);
Enter fullscreen mode Exit fullscreen mode

Clean. Simple. Modern JavaScript.

I ran it:

node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Enter fullscreen mode Exit fullscreen mode

And then the nightmare began.

Day 1: The First Crash 

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '/home/.../node_modules/@solana/kit/'
Enter fullscreen mode Exit fullscreen mode

My reaction: "Oh, dumb mistake. Forgot to install it."

npm install @solana/kit
Enter fullscreen mode Exit fullscreen mode

The result:

npm warn EBADENGINE Unsupported engine {
  package: '@solana/codecs-core@2.3.0',
  required: { node: '>=20.18.0' },
  current: { node: 'v18.20.8' }
}
Enter fullscreen mode Exit fullscreen mode

My reaction: "A warning. Whatever. It'll probably work."

Spoiler alert: It did not work.

Day 2: The Spiral

I spent hours Googling and ChatGPTing lol. Every answer sent me down a different rabbit hole:

  • "Try clearing your cache"
  • "Reinstall node_modules"
  • "Check your package.json"
  • "Use a different RPC endpoint"

Nothing worked.

I checked my package.json:

{
  "dependencies": {
    "@solana/kit": "^0.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Wait. ^0.0.0?

That's not a real version. That's a placeholder.
So I fixed it:

{
  "dependencies": {
    "@solana/kit": "^6.5.0"
  }
}
Enter fullscreen mode Exit fullscreen mode 
rm -rf node_modules package-lock.json
npm install
node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Enter fullscreen mode Exit fullscreen mode

Same error. Nothing changed.

I was losing my mind.

Day 3: The Breakthrough

After hours of debugging, I re-read that warning from Day 1:

required: { node: '>=20.18.0' },
current: { node: 'v18.20.8' }
Enter fullscreen mode Exit fullscreen mode

What if... the warning was actually the error?

I ran:

node --version
# v18.20.8
Enter fullscreen mode Exit fullscreen mode

Then I installed Node 20:

nvm install 20
nvm use 20
node --version
# v20.18.0
Enter fullscreen mode Exit fullscreen mode

Then I ran my script one more time:

node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Enter fullscreen mode Exit fullscreen mode 
=== Solana Account Explorer ===


Address:    TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Balance:    11.977573357 SOL (11977573357 lamports)
Owner:      BPF Upgradeable Loader (BPFLoaderUpgradeab1e11111111111111111111111)
Executable: true
Data size:  36 bytes
Rent epoch: 18446744073709551615
Data (hex): 0200000027f190b1d3af98b8ce714c44e8cadff9f8fc45cb8e5fac4202eff8110d97dd37
Enter fullscreen mode Exit fullscreen mode

IT WORKED.

Three days. 72 hours. For a few line script.

All because I didn't believe the warning.

Why This Happened (The Real Explanation)

Here's what I learned that no tutorial told me:

There Are Two Solana JavaScript Libraries

Library Node.js Required Status
@solana/web3.js (v1) Node 10+ Old but stable
@solana/kit (v2+) Node 20+ New, modern, faster

I was trying to use the NEW library on an OLD Node version.

It's like trying to run a PS5 game on a PS4. The disc fits. The box looks similar. But it will never work.

The Warning Was Actually The Error

Web2 developers (like me) are trained to ignore warnings. "It's just a warning. Your code will still run."

In Web3, the warning IS the error.

When a Solana package says node: '>=20.18.0', it means it. No negotiation. No "probably fine." It requires features that literally don't exist in Node 18.

The Fix (In 3 Commands)

If you're reading this because you're stuck where I was, here's what you do:

# 1. Install nvm (Node Version Manager) if you don't have it
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. Install and use Node 20
nvm install 20
nvm use 20

# 3. Make sure your package.json has a REAL version
npm install @solana/kit@latest
Enter fullscreen mode Exit fullscreen mode

Then run your script again.

If it still doesn't work, delete node_modules and package-lock.json and reinstall:

rm -rf node_modules package-lock.json
npm install
Enter fullscreen mode Exit fullscreen mode

The Prevention Checklist

Before you write a SINGLE line of Solana code, do this:

☐ Check your Node version: node --version
☐ If it's below 20(or the latest node version), upgrade NOW
☐ Install nvm so you can switch versions easily
☐ Read ALL warnings. They're not suggestions.
☐ Verify your package.json has real versions (no ^0.0.0)

The Working Code (Finally)

Here's my complete Solana account explorer. It's simple. It works. And it will save you three days.

import { createSolanaRpc, address } from "@solana/kit";

const RPC_URL = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(RPC_URL);
const inputAddress = process.argv[2];

if (!inputAddress) {
  console.error("Usage: node explorer.mjs <SOLANA_ADDRESS>");
  process.exit(1);
}

try {
  const targetAddress = address(inputAddress);

  // Get balance
  const { value: balanceLamports } = await rpc.getBalance(targetAddress).send();
  const balanceSol = Number(balanceLamports) / 1_000_000_000;

  // Get account info
  const { value: accountInfo } = await rpc
    .getAccountInfo(targetAddress, { encoding: "base64" })
    .send();

  const KNOWN_PROGRAMS = {
    "11111111111111111111111111111111": "System Program",
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA": "Token Program",
    "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb": "Token-2022 Program",
  };

  console.log("\n=== Solana Account Explorer ===\n");
  console.log(`Address:    ${inputAddress}`);
  console.log(`Balance:    ${balanceSol} SOL`);

  if (!accountInfo) {
    console.log(`Status:     Account not found on-chain`);
  } else {
    const ownerLabel = KNOWN_PROGRAMS[accountInfo.owner] || accountInfo.owner;
    console.log(`Owner:      ${ownerLabel}`);
    console.log(`Executable: ${accountInfo.executable}`);
    console.log(`Data size:  ${accountInfo.data[0]?.length || 0} bytes`);
  }

  console.log(`\n🔗 Explorer: https://explorer.solana.com/address/${inputAddress}?cluster=devnet`);
} catch (error) {
  console.error("Error:", error.message);
  process.exit(1);
}
Enter fullscreen mode Exit fullscreen mode

What I Learned (And What You Should Know)

For Web2 Developers Coming to Web3:

  1. Node version matters. Like, REALLY matters. Not "recommended." Required.

  2. Read the warnings. In Web3, warnings are usually errors in disguise.

  3. Install nvm TODAY. Switching Node versions takes 2 seconds. Not having nvm costs days.

  4. There are two Solana libraries. Know which one you're using and what it needs.

  5. Three days of debugging is normal. Don't quit. Everyone goes through this.

The Bottom Line

Your Node.js version WILL break Solana.

Not "might." Not "sometimes." It will break it.

But now you know the fix. And it's simpler than you thought:

Upgrade to latest Node version.

That's it. That's the article.

(I wish someone had just told me that on Day 1.)

Your Turn

Are you doing #100DaysOfSolana? Stuck on a similar error?

Here's what I need you to do right now:

node --version
Enter fullscreen mode Exit fullscreen mode

If it doesn't say v20.x.x or higher, stop everything and upgrade.

Then come back and build something awesome.

I'm documenting my entire #100DaysOfSolana journey. Follow along for more hard-earned lessons, debugging stories, and working code.

Questions? Got your own debugging horror story? Drop a comment or find me on [https://x.com/hxrh__].

Don't hesitate to share this article because it will only cost 4 minutes of reading time and debugging time of 3 days saved. Thank you

Top comments (0)