> ## Documentation Index > Fetch the complete documentation index at: https://www.minitap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting builds > What to do when a build fails, an upload can't run where you picked, or a physical iPhone won't install your app. When a run stops before any scenario starts, the build is usually the reason. This page goes from the message you see to the fix. How builds work in the first place is in [Builds from your repository](https://www.minitap.ai/docs/minitest/setup/builds-from-repo.md) and [Upload a build](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md). | You see | Go to | | - | - | | **BUILD FAILED** on the run | [A build from your repository failed](#a-build-from-your-repository-failed) | | The build is ready but the app crashed at launch | [The app crashed at launch](#the-app-crashed-at-launch) | | **This file type is not supported.**, or a build that can't run on the device you picked | [An upload is rejected](#an-upload-is-rejected) | | An `.aab` that stays converting or fails to convert | [Android App Bundles](#android-app-bundles) | | A TestFlight build that doesn't install | [TestFlight errors](#testflight-errors) | | An Ad Hoc `.ipa` that skips some iPhones | [Ad Hoc profile mismatch](#ad-hoc-profile-mismatch) | | You're not sure which build was tested | [Which build a run used](#which-build-a-run-used) | ## A build from your repository failed The run shows **BUILD FAILED** and no scenario runs, so no credits are used. Open the run: the failure panel explains what went wrong. | In the panel | What it gives you | | - | - | | A label: **Configuration**, **Source code** or **Infrastructure** | The kind of failure, which tells you where to look. **Unclassified** means Mini couldn't return a structured error: read the raw logs. | | **Suggested remediation** | What to change, in plain words. | | **Fix prompt for your AI tool** | A prompt with the error and its context. **Copy fix prompt** and paste it into Cursor or Claude. | | **View raw logs** | The full build output. | What to do depends on the label: * **Configuration**: something the build needs from you is missing, often a build environment variable or a step to add to **Build instructions**. Both live in **Builds & test data → Builds**, see [build environment variables](https://www.minitap.ai/docs/minitest/setup/builds-from-repo.md#build-environment-variables). * **Source code**: the commit itself doesn't compile. Hand the fix prompt to your coding agent, push the fix, and the next run builds the new commit. * **Infrastructure**: usually unrelated to your code. Retry, and tell the Minitap team if it keeps happening. Once the cause is fixed, click **Retry build**. It re-runs the impacted scenarios on the same commit. From the CLI, `minitest build list --status failed` lists failed builds, and `minitest build get ` returns one build with its failure guidance. If the panel says the app's source repository is disconnected from your Git provider, every build fails until you reconnect it in **Settings → Integrations**. A build option you turned on recently, like **Patch RevenueCat**, can also break builds: turn it off and retry, see [build options](https://www.minitap.ai/docs/minitest/setup/builds-from-repo.md#build-options). ## The app crashed at launch After a build, Mini installs the app on a device and runs a quick check before the scenarios start. When the app crashes there, the run says the app crashed when the test agent launched it, and the scenarios are skipped because the app couldn't start. * Open **What the smoke test saw** for the recording of that check, and **View raw logs** for the error. * The usual causes are a missing runtime value, like an API URL the app reads at startup, or a build made for the wrong target. Check your build environment variables, and for uploads, that the file matches the device (next section). * `minitest run logs ` downloads the device log and any crash report. If the banner says the test environment stopped before it could attach an error, retry the run. If it fails again, send the run ID to the Minitap team. ## An upload is rejected The dashboard reads every file you upload and tells you where it can run. Each message points to its fix: | Message | Fix | | - | - | | **This file type is not supported.** | Upload an `.ipa` or `.app.zip` for iOS, an `.aab`, `.apk` or `.apks` for Android. | | This is a device build, signed for real iPhones: the iOS Simulator can't install it. | Switch the iOS row to a physical device, or upload a simulator build. | | This is a simulator build: physical iPhones need a device build (Ad Hoc or Development export). | Export an Ad Hoc or Development `.ipa`, or use a TestFlight link. | | This build only has 32-bit ARM code: emulators need an x86\_64 or arm64 slice. | Pick a physical Android device, or upload the `.aab` or a 64-bit build. | | This build has no phone (arm64) version. | Upload the `.aab` or an `arm64` build to run on phones. | For Android, use a signed `.aab`, or a universal 64-bit `.apk` or `.apks` that isn't a test-only build. From the CLI, a device `.ipa` needs `--physical`, and a simulator build with `--physical` is rejected: the command exits with code 5 and says which flag to change. The table of which file fits which device is in [Upload a build](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md#which-file-for-which-device). A build marked **Flagged as broken** was flagged by an earlier test run. You can still pick it, but expect the same failure. ## Android App Bundles Mini converts an `.aab` into the APKs a device installs. While it converts, the build says it will be ready in a minute or two, and the CLI waits for it unless you pass `--no-wait`. If the bundle can't be converted, the build is marked failed with the reason. Two things don't work on converted builds because Mini signs them with your workspace's key: Play Billing and Play Integrity only trust builds signed by Google Play, and Google sign-in fails until you register the key's SHA-1. `minitest build signing-certificate` prints it. See [Google sign-in](https://www.minitap.ai/docs/minitest/troubleshooting/sign-in.md#google-sign-in-fails). ## TestFlight errors TestFlight builds only run on physical iPhones. * **TestFlight builds run on physical iPhones. Pick a physical device for iOS.** Set the iOS row's **Run on** to **Physical device** in **Run tests**. * **Physical iOS devices are not enabled for this workspace, so TestFlight builds can't run.** Ask for an iPhone, see [Devices](https://www.minitap.ai/docs/minitest/setup/devices.md). * **The run fails with a TestFlight error.** The beta is usually full, or the tester invitation hasn't been accepted. In App Store Connect, open your app's **TestFlight** tab and check that Minitap's Apple ID is an external tester, or that the public link still accepts testers. The iPhone installs whatever build TestFlight serves for the link at run time, so the run report shows the version it actually installed. Setup steps are in [TestFlight and Ad Hoc](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md#physical-iphones-testflight-and-ad-hoc). ## Ad Hoc profile mismatch An Ad Hoc or Development `.ipa` only installs on the iPhones listed in its provisioning profile. Minitap reads the profile of each `.ipa` you upload and runs only on the iPhones in it. In **Builds & test data → In-app purchases**, the **Let the iPhones install your app** step shows the result for your build: | Message | Fix | | - | - | | None of your iPhones are in its profile. | Register the UDIDs, regenerate the profile, archive and upload again. | | It installs on some of your iPhones, with the ones **Not in its profile** listed | Same fix, for the missing iPhones. | | Its profile expired on a given date. | Regenerate the profile and upload a new build. | | It's signed for the App Store: only TestFlight or the App Store can install it. | Export as Ad Hoc or Development, or use a TestFlight link. | | It was uploaded before Minitap read provisioning profiles. | Upload it again to check which iPhones can install it. | The same step lists your workspace's iPhones with **Copy UDID**. Register them in **developer.apple.com › Devices**, regenerate your **Ad Hoc** or **Development** profile so it includes them, and archive with the team that owns the app in App Store Connect. Every new iPhone in your workspace means a new profile and a new upload. A TestFlight link skips both. ## Which build a run used The **Build Version** column of the runs list, **Run info** on the run page, and `minitest build get ` all show the version, build number and commit. Details are in [which build a run used](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md#which-build-a-run-used) and [did Mini run the right build?](https://www.minitap.ai/docs/minitest/troubleshooting/runs.md#did-mini-run-the-right-build). ## Still stuck? Send the Minitap team the run ID and the build's raw logs in your Slack channel. If you don't have one yet, [book a call](https://cal.com/team/minitap/minitap-get-access?overlayCalendar=true). > [card] [Builds from your repository](https://www.minitap.ai/docs/minitest/setup/builds-from-repo.md) > > The settings that shape a build from your code. > [card] [Upload a build](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md) > > Which file fits which device, TestFlight and Ad Hoc. > [card] [Troubleshooting runs](https://www.minitap.ai/docs/minitest/troubleshooting/runs.md) > > Long runs, Mini's questions and false failures. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.