Solving Nixpacks Node Version Issues with a custom nixpacks.toml

If you’ve tried upgrading your app to Node.js 22+ on a hosting service like Railway and hit walls despite doing everything right, you’re not alone. We recently ran into a frustrating issue where Nixpacks refused to use the correct Node.js version—even though we specified it everywhere.

The Problem: Node Version Inconsistencies in Nixpacks

We needed to deploy an app that required Node.js >= 22.12.0 for compatibility with Directus 11. But when deploying to staging or production, the Railway builds kept using a version that was one patch lower than needed, breaking the app at runtime.

We tried all the usual methods:

What Didn't Work:

• Setting NIXPACKS_NODE_VERSION=22,this ENV only allows setting major versions like 22 and not 22.12.0
• Adding "engines": { "node": ">=22.12.0" } in package.json
• Adding an .nvmrc file with 22.12.0

Despite all of that, the builds would still pick up a lower version, causing failure.

The Fix: Use nixpacks.toml with a nixpkgsArchive Pin

The only reliable way to force the correct Node.js version was to override the Nixpacks base archive by creating a nixpacks.toml file:

[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'

This commit hash from the NixOS/nixpkgs repo provides Node.js 22.13.1, which works perfectly with Directus 11.

The correct version was picked up, and our builds succeeded.

Why This Works

The nixpkgsArchive pin tells Nixpacks to use a specific commit of the Nix package repository, locking in the exact Node.js version available in that snapshot.

Without this, hosting sites like Railway use a default nixpkgs archive—which may lag behind or skip specific Node versions.

Note: This approach is similar to pinning dependencies in package-lock.json, but for your system-level environment.

Finding the Right nixpkgs Commit for Your Version

Want a different Node.js version in the future? You’ll need to find the right nixpkgs commit. Here’s how:

1. Go to the nixpkgs GitHub repo.
2. Navigate to: pkgs/development/web/nodejs/
3. Check the v22.nix file across commits to find the one that introduced your desired version.

Known Working Commits

Commit Hash	Node.js Version
51ad838b03a05b1de6f9f2a0fffecee64a9788ee	✅ 22.13.1 (Confirmed working)
bf744fe90419885eefced41b3e5ae442d732712d	✅ 22+ versions available
ffeebf0acf3ae8b29f8c7049cd911b9636efd7e7	⚠️ 22.14.0 (from master, may be unstable)

For more info, check out Nixpacks GitHub Issue #1017, where this workaround is discussed.

By using nixpkgsArchive, you get deterministic builds and avoid the frustrations of version mismatches, especially when platform requirements (like Directus needing Node >=22) are strict.

Let us know if you’ve hit this and found another workaround. Happy deploying!

Resources

• Nixpacks Documentation