Skip to main content

Debugging your build on your own machine


If your build fails on Bitrise, we often recommend to try and run it locally. To debug: use a full clean git clone, and run the build on your machine with the Bitrise CLI.

If your build fails on Bitrise, we often recommend to try and run it locally, on your machine. To do this, do the following:

  • Do a full clean git clone of your project’s online repository.

  • Run the build on your machine with the Bitrise CLI.

This helps to eliminate, among other things, a very common issue: that uncommitted or gitignored files are in your working directory but they haven’t been committed into your git repository online and therefore they are not available when Bitrise clones the repository for running the build. Other possible issues include:

  • Code signing files are present on your local machine but not uploaded to Bitrise.

  • A difference in the version of the tool(s) used for the build.

Testing with a full clean git clone

  1. Open your Terminal / Command Line interface on your machine.

  2. Type in: cd /tmp

  3. Clone your repository with: git clone REPOURL ./quick-repo-test --branch BRANCH-YOU-WANT-TO-TEST:

    git clone ./quick-repo-test --branch master
  4. Type cd ./quick-repo-test.

Run the commands you want to test, to build your project, or to open the project file from this directory.

Testing with the Bitrise CLI

After doing a full clean git clone, run a build locally, using the Bitrise CLI.

  1. Install the Bitrise CLI.

  2. Download your app’s bitrise.yml file from

  3. Run the build with: bitrise run <workflow-name> (for example, bitrise run primary).

This should help reproducing the issues in most cases, and allows you to attempt to debug them on your own machine.

If the build succeeds under these conditions but still fails on Bitrise, contact our support!

Android projects

If you still can’t reproduce the issue locally, you might also want to delete the $HOME/.gradle (hidden) directory, to clear your Gradle caches. (Quick Terminal / Command Line command: rm -rf $HOME/.gradle).

Run docker from a clean git clone

If your project uses the Android/Linux environment, you can download and use the exact same environment as the one your build is running in on

Ideally, you should first do a clean git clone and run docker from there, so that files which are in your .gitignore won’t affect the build, and the build can run the the same way as on