Heroku Build Failed Error

How to fix it

Try these in order — the most common fix is first.

1. 1. Read the build output

   Copy steps
   1. Scroll to the first error in the remote: lines
   2. Search that exact message; most are dependency or version errors
   Did this fix it? Yes No

2. 2. Confirm the buildpack

   Copy steps
   1. Run heroku buildpacks
   2. Set it: heroku buildpacks:set heroku/nodejs (or heroku/python, heroku/ruby)
   Did this fix it? Yes No

3. 3. Pin the runtime version

   Copy steps
   1. Node: add "engines": {"node": "22.x"} to package.json
   2. Python: add runtime.txt or .python-version
   3. Match your local version
   Did this fix it? Yes No

4. 4. Sync and commit the lockfile

   Copy steps
   1. npm install / yarn install / pnpm install
   2. Commit package-lock.json, yarn.lock or pnpm-lock.yaml
   Did this fix it? Yes No

5. 5. Do not commit node_modules

   Copy steps
   1. git rm -r --cached node_modules
   2. Add node_modules to .gitignore
   3. Check .gitignore rules like lib/ that may exclude real source folders; use /lib
   Did this fix it? Yes No

6. 6. Run the build in a one-off dyno

   Copy steps
   1. heroku run bash -a <staging-app>
   2. Run your build script there with --verbose to see the real error
   Did this fix it? Yes No

7. 7. Clear the build cache if it is stale

   Copy steps
   1. Install the heroku-builds plugin: heroku plugins:install heroku-builds
   2. Run heroku builds:cache:purge -a <app> then redeploy
   Did this fix it? Yes No

Symptoms

git push heroku main ends with '! Push rejected, failed to compile ... app' or 'Build failed'.

Why it happens

• Wrong or missing buildpack
• Node, Python or Ruby version mismatch
• Lockfile not committed or out of sync
• node_modules or other generated folders committed
• devDependencies pruned but needed at runtime
• Build script that only works locally

This guide also covers

• heroku build failed
• heroku push rejected failed to compile
• heroku buildpack error
• heroku deploy failed

The same problem in other apps

All export, render & quality loss guides →

• DigitalOcean App Platform Build Failed (DigitalOcean)
• Vercel Deployment Failed: Build Error (Vercel)

Other Heroku errors

• Heroku H10 App Crashed Error
• Heroku H12 Request Timeout Error
• Heroku R14 Memory Quota Exceeded Error
• Heroku Application Error Page
• Heroku Git Push Rejected / Remote Rejected
• Heroku H14 No Web Dynos Running
• Heroku R10 Boot Timeout / H20 App Boot Timeout
• Heroku Custom Domain SSL Certificate Not Working