Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

git push heroku fails while building a Node.js app

ErrorResolving node version 22.x...

Short answer

When a Heroku Node.js build fails, the push is rejected and the reason sits in the remote lines just above the failure. The usual causes are a lockfile that no longer matches package.json, an engines.node value with no matching release, proxy variables that block the Node download, and node_modules committed to Git.

  • Applies to Heroku Node.js buildpack, Node.js 22, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Re-run the push and read the remote output from the top. The buildpack prints each step, and the first line starting with ! names the failing one. Do not start from the last line.

    git push heroku main 2>&1 | tee build.log
    heroku builds:info -a example-app
  2. 2Match what you see, then jump to its fix

    1. 1The failure happens in the install step, before any of your scripts runpackage-lock.json is out of date with package.jsonFix
    2. 2The log shows Resolving node version ... and then a warning and a failureengines.node asks for a version that does not existFix
    3. 3Error: Unknown error installing "22" of node, with a curl SSL_ERROR_SYSCALL line for amazonaws.comA proxy variable blocks the download of Node.jsFix
    4. 4The build works locally but fails on Heroku with missing or mismatched filesnode_modules or another generated folder is committed, or a needed file is ignoredFix
    5. 5The log ends inside your own heroku-postbuild or build scriptA build script that only fails on HerokuFix

What does the error look like?

  • Resolving node version 22.x...
  • Error: Unknown error installing "22" of node
  • curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to lang-common.s3.amazonaws.com:443

Cause 1 of 5

package-lock.json is out of date with package.json

1Check

Heroku installs from the lockfile (npm ci by default for npm), so a lockfile that disagrees with package.json cannot be installed. Run the same command locally.

npm ci

2Fix

Regenerate the lockfile with your package manager, then commit it together with package.json.

npm install
git add package.json package-lock.json
git commit -m "Update lockfile"

3Verify

npm ci succeeds locally, and the next push gets past the install step.

npm ci
git push heroku main

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 2 of 5

engines.node asks for a version that does not exist

1Check

Heroku prints the range it is resolving. If the range matches no published release, the build prints a warning and fails. Compare it with your local versions.

node --version
npm --version
grep -A3 '"engines"' package.json

2Fix

Set engines to a version that exists, preferably a major range such as 22.x. The platform page lists the supported lines.

{
  "engines": {
    "node": "22.x"
  }
}

3Verify

The build log shows the version resolved and the install begins.

git push heroku main

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 3 of 5

A proxy variable blocks the download of Node.js

1Check

Proxy config vars (HTTP_PROXY, HTTPS_PROXY) send the buildpack's own download through your proxy. Look at what is set on the app.

heroku config -a example-app | grep -i proxy

2Fix

Remove the proxy variables, or let the AWS host bypass the proxy.

heroku config:unset HTTP_PROXY HTTPS_PROXY -a example-app
# or keep the proxy and exempt the host
heroku config:set NO_PROXY=amazonaws.com -a example-app

3Verify

Push again. The Node.js download step passes.

git push heroku main

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 4 of 5

node_modules or another generated folder is committed, or a needed file is ignored

1Check

Folders created by npm and build tools should not be in Git, and an over-broad .gitignore rule can hide a source file. A rule such as lib/ matches nested folders too.

git ls-files | grep node_modules
git check-ignore -v src/lib/example.js

2Fix

Untrack the generated folder and ignore it. If a rule hides a real file, anchor it to the root, for example /lib.

echo "node_modules" >> .gitignore
git rm -r --cached node_modules
git commit -am "Stop tracking node_modules"

3Verify

git ls-files shows no node_modules, and the push builds from a clean state.

git ls-files | grep -c node_modules

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 5 of 5

A build script that only fails on Heroku

1Check

If heroku-postbuild exists, the plain build script is not run. Reproduce the script in a one-off dyno that has the same slug and environment.

heroku run bash -a example-app
npm run build --verbose

2Fix

Fix what the script prints. Build tools that your script needs must be installed during the build; they are pruned from devDependencies after heroku-postbuild runs, so run the build step there.

"scripts": {
  "start": "node server.js",
  "heroku-postbuild": "npm run build"
}

3Verify

The push completes and the build log shows the script finishing.

git push heroku main

Confirmed by devcenter.heroku.com

Did this fix it?

How do I stop it coming back?

  • Commit package-lock.json every time you change dependencies, and run npm ci locally before pushing.
  • Pin engines.node to a major range such as 22.x so the platform default does not change under you.
  • Keep node_modules and build output in .gitignore from the first commit.
  • Add a start script or a Procfile so the web process is defined once the build passes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.