Debugging your build on your own machine

Japanese translation unavailable

This page has not been translated into Japanese yet - we apologise for the inconvenience! If you’re interested in helping us out, feel free to translate any article in the jp folder of the DevCenter repository and open a PR!

このページは日本語への翻訳がまだ完了しておりません。ご不便をおかけして申し訳ございません! もしお手伝いできる方がいらっしゃれば、ご自由にjpフォルダの記事を日本語に訳していただき、PRを開いてください

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

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:

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
    • example: 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!

Running iOS tests

  • Make sure that you run the tests in the same simulator as the one runs. If you use the Bitrise CLI to run the tests locally this is not required, that uses the same configuration.
  • If you’re debugging an iOS unit/UI test issue, please make sure to reset the iOS Simulator (in the Simulator app, select the Simulator menu bar item -> then Reset Content and Setting).

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)

Using the Android/Linux environment locally

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

Follow our guide to make it work!

Run docker from a clean git clone

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