[build-utils] Optimize getAvailableNodeVersions to skip discontinued versions (#14686)

ofhouse · web-flow · commit ee4463453cfe · 2026-01-22T12:31:13.000+01:00
## Summary

- Optimize `isNodeVersionAvailable` to use `statSync` with `{
throwIfNoEntry: false }` instead of try-catch pattern for better
efficiency
- Skip old Node versions (&lt; 18) in `getAvailableNodeVersions` to avoid
unnecessary filesystem checks for versions that don't exist in the build
container
- Update error message to mention "discontinued" versions for better
user guidance

## Changes

1. **Non-throwing `statSync`**: Replace try-catch block with
`statSync(path, { throwIfNoEntry: false })` which returns `undefined`
instead of throwing when the path doesn't exist

2. **Filter old versions**: Add a filter to skip Node versions &lt; 18
(e.g., Node 8, 10, 12, 14, 16) before checking filesystem availability,
as these versions don't have directories in the build container. This
reduces unnecessary `statSync` calls while preserving behavior for Node
18+ which still have directories available.

3. **Improved error message**: Change error from `"Found invalid Node.js
Version"` to `"Found invalid or discontinued Node.js Version"` to give
users a hint that their requested version may have been discontinued
diff --git a/.changeset/eager-bananas-optimize.md b/.changeset/eager-bananas-optimize.md
@@ -0,0 +1,5 @@
+---
+'@vercel/build-utils': patch
+---
+
+Optimize `getAvailableNodeVersions` to skip discontinued versions and use non-throwing `statSync`
diff --git a/packages/build-utils/src/fs/node-version.ts b/packages/build-utils/src/fs/node-version.ts
@@ -79,18 +79,18 @@ function getOptions(): NodeVersion[] {
 }
 
 function isNodeVersionAvailable(version: NodeVersion): boolean {
-  try {
-    return statSync(`/node${version.major}`).isDirectory();
-  } catch {
-    // ENOENT, or any other error, we don't care about
-  }
-  return false;
+  const stat = statSync(`/node${version.major}`, { throwIfNoEntry: false });
+  return stat?.isDirectory() ?? false;
 }
 
 export function getAvailableNodeVersions(): NodeVersionMajor[] {
-  return getOptions()
-    .filter(isNodeVersionAvailable)
-    .map(n => n.major);
+  return (
+    getOptions()
+      // Only check versions >= 18, as older versions don't have directories in the build container
+      .filter(v => v.major >= 18)
+      .filter(isNodeVersionAvailable)
+      .map(n => n.major)
+  );
 }
 
 function getHint(isAuto = false, availableVersions?: NodeVersionMajor[]) {
@@ -149,7 +149,7 @@ export async function getSupportedNodeVersion(
       throw new NowBuildError({
         code: 'BUILD_UTILS_NODE_VERSION_INVALID',
         link: 'https://vercel.link/node-version',
-        message: `Found invalid Node.js Version: "${engineRange}". ${getHint(
+        message: `Found invalid or discontinued Node.js Version: "${engineRange}". ${getHint(
           isAuto,
           availableVersions
         )}`,
diff --git a/packages/build-utils/test/unit.test.ts b/packages/build-utils/test/unit.test.ts
@@ -141,7 +141,7 @@ it('should only nodejs24.x', async () => {
 it('should not allow nodejs18.x when not available', async () => {
   // Simulates AL2023 build-container
   await expect(getSupportedNodeVersion('18.x', true, [20])).rejects.toThrow(
-    'Found invalid Node.js Version: "18.x". Please set Node.js Version to 20.x in your Project Settings to use Node.js 20.'
+    'Found invalid or discontinued Node.js Version: "18.x". Please set Node.js Version to 20.x in your Project Settings to use Node.js 20.'
   );
 });
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@vercel/build-utils': patch
 +---
++
 +Optimize `getAvailableNodeVersions` to skip discontinued versions and use non-throwing `statSync`