git push heroku fails while building a Node.js app
Resolving 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.
Fix it fast
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-app2Match what you see, then jump to its fix
- 1
The failure happens in the install step, before any of your scripts runpackage-lock.json is out of date with package.jsonFix - 2
The log shows Resolving node version ... and then a warning and a failureengines.node asks for a version that does not existFix - 3
Error: 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
The 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
The log ends inside your own heroku-postbuild or build scriptA build script that only fails on HerokuFix
- 1
What does the error look like?
Resolving node version 22.x...Error: Unknown error installing "22" of nodecurl: (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 ci2Fix
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 mainConfirmed by devcenter.heroku.com
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.json2Fix
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 mainConfirmed by devcenter.heroku.com
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 proxy2Fix
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-app3Verify
Push again. The Node.js download step passes.
git push heroku mainConfirmed by devcenter.heroku.com
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.js2Fix
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_modulesConfirmed by devcenter.heroku.com
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 --verbose2Fix
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 mainConfirmed by devcenter.heroku.com
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix