GitHub Actions setup-node "Unable to find Node version" in CI

actions/setup-node could not resolve the requested Node version - the version or range matches nothing in the manifest, the .nvmrc/.node-version file is missing, or a transient download failure occurred.

What this error means

The Setup Node step fails with "Unable to find a version that satisfied the version spec", or a network error while downloading the Node distribution.

Error: Unable to find a version that satisfied the version spec '20.99'
# or
Error: getaddrinfo EAI_AGAIN nodejs.org

Common causes

Version or range matches nothing

A node-version like 20.99 or an over-narrow range has no published release. setup-node resolves against the version manifest and finds no match.

Missing version file

Using node-version-file pointed at a .nvmrc or .node-version that does not exist (or is empty) leaves setup-node with nothing to resolve.

Transient download failure

A momentary network or mirror blip while fetching the Node tarball fails the step even though the version is valid.

How to fix it

Request a resolvable version

Use a major version or a valid range so setup-node can pick the latest matching release.

- uses: actions/setup-node@v4
  with:
    node-version: '20'   # latest 20.x
    check-latest: true

Fix the version file or retry

1. Ensure .nvmrc / .node-version exists and contains a valid version when using node-version-file.
2. Re-run the job if the failure was a download/network error.
3. Pin to an LTS major (18, 20, 22) rather than an exact patch that may not exist.

How to prevent it

• Pin to a major version or LTS line rather than an exact unverified patch.
• Commit a valid .nvmrc when using node-version-file.
• Treat one-off download failures as transient and retry.

Related guides