Troubleshooting builds

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 and Upload a build.

​

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. 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.
• 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 <build_id> 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.

​

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 <run_id> 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: 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. 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.

​

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.
• 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.

​

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: 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 <build_id> all show the version, build number and commit. Details are in which build a run used and 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.