actions/setup-node "Could not resolve dist for node-version-file"

By Daniel Zoghalchali·Latchkey

setup-node reads the version from the path in node-version-file. A missing file, a path-not-checked-out, or a malformed value leaves no resolvable version.

What this error means

The setup-node step fails with "Could not resolve a version" or cannot find node-version-file.

Error: Could not resolve a version from the file: .nvmrc
##[error]The node-version-file was not found.

Diagnose it: was the cache hit, and was it the right one?

Cache bugs split into three shapes and they need different fixes: the cache never saved, it saved but the key never matches on restore, or it restored a stale entry through a restore-keys prefix and is now poisoning the build. The step output tells you which one you have.

- uses: actions/cache@v4
  id: cache
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- name: What happened
  run: |
    echo "exact hit: ${{ steps.cache.outputs.cache-hit }}"
    echo "key used:  ${{ steps.cache.outputs.cache-matched-key }}"

Common causes

File missing or not checked out

The repo was not checked out, or the path does not point at the version file.

Malformed version value

The file contains a value setup-node cannot parse into a Node version.

How to fix it

Checkout first and point at a valid file

1. Run actions/checkout before setup-node.
2. Set node-version-file to a real path with a valid version (.nvmrc or package.json engines).
3. Re-run the setup step.

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version-file: .nvmrc
    cache: npm

Cache limits that produce confusing failures

• Repository cache is capped at 10 GB. Past that, GitHub evicts least-recently-used entries, so a large cache can silently stop persisting.
• Caches are scoped by branch. A cache written on a feature branch is not visible to another feature branch, only to its base and its own descendants.
• An entry not read for 7 days is evicted, so a rarely-run workflow effectively never has a warm cache.
• Restoring a cache built for a different tool version is worse than a cold start, because you get a corrupted tree instead of a clean install. Always include the tool version in the key.

How to prevent it

• Always checkout before any setup-* that reads a repo file.
• Keep .nvmrc / engines values in a format setup-node accepts.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions