How to debug your build locally?

Issue also known as “It works on my Mac/PC but not on”. Be like Sherlock and investigate using Bitrise CTO Viktor Benei's guide. 🕵

Issue also known as “It works on my Mac/PC but not on”. Be like Sherlock and investigate! 🕵

If the build works on your local Mac/PC but not on, that’s usually because of uncommitted / gitignored files or a tool version difference. There can be other reasons, for example in case of iOS, code signing errors: it’s usually because of a code signing file which is available on your Mac, but which you did not upload to and so it’s not available there.

In any case, the first steps you should try, preferably before you’d report the issue (as this will be the first thing we’ll ask for anyway ;)) is to make a full clean clone of your project, and try to run the build there. This helps to eliminate the most common issue: that you have a file in your project’s regular working directory which is not committed into git, and so it’s not available when clones the repository.

Testing with a full clean git clone

  1. open your Terminal / Command Line
  2. type in: cd /tmp
  3. clone your repository with: git clone REPOURL ./quick-repo-test --branch BRANCH-YOU-WANT-TO-TEST
  4. example: git clone ./quick-repo-test --branch master
  5. cd ./quick-repo-test

and then run the commands you want to test to build your project, or open the project file from this directory (you can open the directory in Finder / file browser by typing in: open .).

Test with Bitrise CLI

You can also run the same build locally, using the Bitrise CLI. For this, follow the steps in the previous section (Testing with a full clean git clone), and once you’re in the /tmp/quick-repo-test directory:

  1. Make a clean git clone, as described in the previous section: Testing with a full clean git clone
  2. Install the Bitrise CLI following the install instructions (it takes less than a minute to install it, the Bitrise CLI is distributed as a single binary, without any installer)
  3. Download your app’s bitrise.yml from
  4. open the app on
  5. click the Workflow tab to open the Workflow Editor
  6. on the left side select bitrise.yml
  7. download the yml and save it into /tmp/quick-repo-test with the file name bitrise.yml
  8. Now that you have the bitrise.yml in /tmp/quick-repo-test, run the build with: bitrise run WORKFLOW-TO-RUN (e.g. bitrise run primary)

This should help reproduce the issue in most cases.

Additional notes for iOS projects

  • 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 Settings…).

Additional notes for Android/Gradle projects

  • If you still can’t reproduce the issue locally (after following the previous steps), 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)

Download and use the Android/Linux environment

This only works if your project uses the Android/Linux environment. If you do, that’s awesome, as you can download and use the exact same environment as the one your build is running in on!

To do this, please follow this guide.

For best efficiency you should first do a clean git clone (as described above -> Testing with a full 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 way how it runs on

If it still doesn’t work

Please report the issue on Discuss or ping our support via the onsite chat - we’ll try to help as soon as possible!

Happy investigating! 🕵

No items found.
The Mobile DevOps Newsletter

Explore more topics

App Development

Learn how to optimize your mobile app deployment processes for iOS, Android, Flutter, ReactNative, and more

Bitrise & Community

Check out the latest from Bitrise and the community. Learn about the upcoming mobile events, employee spotlights, women in tech, and more

Mobile App Releases

Learn how to release faster, better apps on the App Store, Google Play Store, Huawei AppGallery, and other app stores

Mobile DevOps

Learn Mobile DevOps best practices such as DevOps for iOS, Android, and industry-specific DevOps tips for mobile engineers

Mobile Testing & Security

Learn how to optimize mobile testing and security — from automated security checks to robust mobile testing and more.

Product Updates

Check out the latest product updates from Bitrise — Build Insights updates, product news, and more.

The Mobile DevOps Newsletter

Join 1000s of your peers. Sign up to receive Mobile DevOps tips, news, and best practice guides once every two weeks.