If you have an issue with your application, consider and try to rule out the following:

  • Database connectivity issues.
  • Environment variables:
  • Incorrect variables.
  • Special characters.
  • Base64 Encoded Variables.
  • Connectivity issues with external applications.
  • Bad Start commands. For example, if you are trying to use yarn when only npm is available, or a package.json file without the required start script.
  • When chaining Start commands, the last command must initiate a web service. This keeps the container running and listening to incoming connections.
  • An invalid package name in package.json. For example, do not use “js” or “node” in the name. For more details, see the specifics of npm’s package.json handling in the npm Docs.
  • Permission issues.
  • Missing files.

​
General troubleshooting steps

  1. Change the start command to sleep 9999. This will get the pod into a running state where you can interact with it via the Web terminal. Edit the web process to change the start command (Processes > Web process > Edit process).
  2. Open the Web terminal.
  3. Check the environment variables. In the web terminal, enter printenv and check that the environment variables are what you expect them to be.
  4. Run the application manually. Try running the application manually with debug options enabled. The command to do this may vary, depending on the application. For more details, check the documentation for the language or package manager your application is built with.
  5. Try to build the application locally:
  • For Buildpacks, you can use the pack build command to build your container images locally. For example:
pack build <image name> --path <application directory> --buildpack heroku/<buildpack name> -v
  • For Nixpacks, you need to install Nixpacks locally and run nixpacks build within your application directory.