Troubleshooting Node.js Deploys
Last updated 11 December 2018
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 package.json 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 10.x...
remote: Downloading and installing node 10.3.0...
remote: Using default npm version: 6.4.1
They should match up with the same versions you saw locally. If they don’t, you should specify the matching versions in your package.json.
Don’t check in generated directories
Your app’s node_modules directory is generated at build time from the dependencies listed in package.json. Therefore, 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 node_modules:
$ 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 NODE_ENV environment variable. This is especially common when building web assets to avoid the overhead minifying JavaScript and compressing images during development.
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 to production.
$ NODE_ENV=production npm start
Check your .gitignore
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 .gitignore file.
As an example, you might wish to exclude a lib directory at the root of your application, but the rule:
lib/
in your .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.
/lib
Open a ticket
If none of these solutions work for you, open a ticket with Heroku so we can help.