Troubleshooting Node.js Deploys
Last updated 21 October 2019
Table of Contents
Your Node.js deploy failed - now what? Start with these simple steps to troubleshoot a build issue.
Check your buildpack
Are you using the officially supported and maintained buildpack, or something else? Most of the time, the standard buildpack is the best choice - either alone, or paired with other buildpacks (like Ruby).
Find out by running:
$ heroku buildpacks
To use the official buildpack:
$ heroku buildpacks:set heroku/nodejs
Compare Node and npm Versions
Your production environment should mirror your development environment, especially in the case of important binaries. First, check your local versions:
$ node --version $ npm --version
Then, compare the results with your
engines section. You are specifying a node version, right?
You can see which binaries Heroku is using on each deploy in the build logs, which look something like this:
remote: -----> Installing binaries remote: Resolving node version 12.x... remote: Downloading and installing node 12.13.0... remote: Using default npm version: 6.11.3
They should match up with the same versions you saw locally. If they don’t, you should specify the matching versions in your
Don’t check in generated directories
node_modules directory is generated at build time from the dependencies listed in
node_modules (and other generated directories like
bower_components) shouldn’t be included in source control. It’s easy to check:
$ git ls-files | grep node_modules
If you see a list of results, then you should instruct git to stop tracking
$ echo "node_modules" >> .gitignore $ git rm -r --cached node_modules $ git commit -am 'untracked node_modules'
Check for differences between development and production
Many Node applications have checks that will perform different logic based on the value of the
Occasionally this can lead to subtle bugs that will only show up when trying to deploy. If you run into a new bug while deploying check to see if it can be reproduced locally by setting
$ NODE_ENV=production npm start
A required file may exist locally, but it’s possible to accidentally prevent it from being included in your git repo by an overly broad rule in your
As an example, you might wish to exclude a
lib directory at the root of your application, but the rule:
.gitignore will recursively match any subdirectory named
lib, so the file
js/library-name/lib/index.js would not be included in your git repo. You can fix this case by moving the slash to the front, which will only match the
lib directory in the application root directory.
Open a ticket
If none of these solutions work for you, open a ticket with Heroku so we can help.