Basics: Troubleshooting Build Failures

The Basics

What happens when you push?

When you use git push ionic master to push a new commit to Ionic Appflow, our platform adds the commit to your Commits page.

From there, you can choose to run a new Deploy (or "Web") build or a Package build at your convenience (or automate the process using Automations if supported by your plan type).

The following steps are run during a Deploy or a Package build:

1. npm install, which will pull in all of your app's node dependencies from the NPM registry.

2. npm run build, which will execute whatever build script is specified in the scripts field in your app's package.json. By default, for Ionic-Angular projects this is ionic-app-scripts build. The purpose of this build is to generate your app's frontend assets and place them in a www/ directory in the app's root.

Note: This step is skipped for Ionic 1 apps. They do not require a build, since the www/ directory is directly committed.

Why do they fail?

The most important point to keep in mind about these builds is the package.json file is the only source of truth for your app's node dependencies. Most often, when a build fails, it is because some package is missing from from the version of package.json that has been pushed to Ionic Appflow. 

Troubleshooting

Running a "Clean" Build

Since the most likely issue is a discrepancy between your local project and what you've committed, the best way to troubleshoot is to sync those two environments by following these steps:

1. Delete the app's node_modules/​ directory

3. Run npm install​ (which will regenerate what you deleted above)

4. Run npm run build​

Most likely, you will then see the same error you saw in the build log on your Ionic Appflow dashboard. The error messages should point you in the right direction of what needs to be updated.

Note also that packages have their own dependencies. Frequently, an app installs one version of a package, then another dependency tries to install another version, and the collision between the two causes an error. 

Once you have updated your dependencies, repeat the steps above. Once the build succeeds locally, re-commit and push to Ionic, and the build should work on our platform as well. 

Some helpful tools

• $ ionic doctor check : to check on the health of your Ionic project
• $ npm list : to list your npm packages, and any errors and warnings
• $ npm outdated : see what packages are out of date

Some best practices

• Stay up to date on all dev dependencies, particularly ionic-angular and ionic-app-scripts.
• Always include the --save flag when adding Cordova plugins and platforms
• Get very familiar with NPM and semver