Troubleshooting a Failed Build

Last Updated January 2015

As code is pushed and deployed to Pagoda Box, it must first go through a build process to prepare the code for its live environment. In some cases, errors can cause to build to fail and abort . This doc explains what a failed build is and what you can do to identify and fix the issue. After reading it, you should be familiar with:

  • Identifying why a build fails
  • Using deploy logs to troubleshoot builds

What Does it Mean When a Build Fails?

Anytime code is pushed to Pagoda Box, it must first be prepped for deploy. This preparation phase is referred to as the “build.” During a build, commands known as build hooks run to prepare the code and make any modifications necessary to get the app ready for a production environment. If an error is thrown during a build hook and the command exits with a status anything other than “0”, the hook will abort and the build will fail.

How to Find & Fix Build Issues

Since build hooks are simply commands/scripts that run during the build phase, there’s a limitless number of reasons a build could fail. The key to finding why a build has failed is your app’s deploy logs.

Check Your Deploy Logs

All output from build hooks are stored in your app’s deploy logs, available in your dashboard. If a script or command fails, the error is typically output and will be viewable here.

Custom Script Output

If running a custom script in a build hook, errors may be suppressed. It is up to you to code-in or enable error output for custom scripts used in build hooks.

Make Necessary Changes to Your Code

Depending on the cause of the error in the build hook, you may either need to modify your hook command or the code that’s used by the hook.

If you have any questions, suggestions, or corrections, let us know.