Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Rails Support
      • Working with Bundler
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • Kotlin
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
    • Single Sign-on (SSO)
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Language Support
  • ›
  • Node.js
  • ›
  • Troubleshooting Node.js Deploys

Troubleshooting Node.js Deploys

Last updated 11 December 2018

Table of Contents

  • Check your buildpack
  • Compare Node and npm Versions
  • Don’t check in generated directories
  • Check for differences between development and production
  • Check your .gitignore
  • Open a ticket

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.

Keep reading

  • Node.js
  • Heroku Node.js Support
  • Using Multiple Buildpacks for an App

Feedback

Log in to submit feedback.

Scaling an Express.js Application with MemcacheTroubleshooting Node.js Memory Use

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies