Troubleshooting
The failures we see most often, what actually causes them, and how to tell them apart from each other.
If none of this matches, send us the build URL. We can see the same log you can, plus the machine-side detail you cannot, and we would rather look than have you guess.
01It works on my Mac but not here
Almost always one of three things, in this order of likelihood:
- The file is not committed. The build machine has exactly what is in your repository at that ref — no .env, no local config, no file you created last month and forgot to add. Run git status --ignored on your own machine and look at what it hides.
- A dependency resolved to a different version. Commit your lockfiles — Podfile.lock, package-lock.json, pubspec.lock, Package.resolved. Without them, “it worked yesterday” is not a claim about your code.
- A tool is installed on your Mac and not in the image. Add a brew install line. Homebrew is there and works.
A private submodule or dependency fails at once with could not read Username for 'https://github.com': terminal prompts disabled. That is deliberate: an unattended build must never sit waiting for a password, so we switch prompting off and git gives up in about a second. Clone it with a token from Secrets — https://x-access-token:$GH_TOKEN@github.com/... — or make it public.
A quick way to see the gap: make your first script step git ls-files | head -50. The list of what the machine actually received is often enough on its own.
02The build hangs and then hits the time limit
Something is waiting for a human. The machine has no keyboard, so it waits forever.
| Waiting on | Fix |
|---|---|
| An interactive installer (apt-style prompts, gem install asking to overwrite) | Add the tool's non-interactive flag — -y, --yes, --non-interactive. |
| A simulator that never boots | Name a simulator that exists. OS=latest with a device name is safer than pinning an OS version that the image may not have. |
| Your own test suite waiting on a network service | Builds reach the public internet but cannot reach anything on your network. Stub it. |
Free builds stop at 30 minutes, paid builds at 2 hours. A build that hits the limit is billed for the time it used — a hang is not free, so it is worth putting a time limit on any step you suspect.
macOS has no timeout command, and a script copied from a Linux CI will fail on it with command not found. Either of these works here:
# no install needed: perl is part of macOS
- perl -e 'alarm shift; exec @ARGV' 300 ./scripts/integration-tests.sh
# or GNU timeout, from Homebrew
- brew install coreutils
- gtimeout 300 ./scripts/integration-tests.sh
03Artifacts are missing from a green build
The build succeeded and the artifacts list is empty. The glob did not match. Add this as your last script line and read the log:
- ls -la build/ios/iphoneos/ || true
Three things that catch people:
- Globs are matched from the root of your checkout, not from wherever your last cd left you.
- A single file over 500 MB is skipped, and so is anything past 1 GB in one build. The log says which.
- *.ipa does not match build/ipa/MyApp.ipa. Use build/ipa/*.ipa or **/*.ipa.
Artifacts are kept for 30 days and then deleted — or for fewer days, if you shortened it under Activity & data. Download links you share are valid for 24 hours; the artifact itself outlives the link.
04Your .tar.gz arrived as a .tar
A folder-shaped artifact — Runner.app, an .xcarchive, a .dSYM bundle — is packed into a single .tar.gz before it leaves the build machine. Safari, with Open “safe” files after downloading switched on, unpacks the outer gzip as soon as the download lands and removes the .gz. You get a valid .tar, larger than the number you saw in the download list. Nothing is wrong with the artifact.
To keep the file exactly as we sent it, turn that setting off in Safari → Settings → General, or download with curl. Chrome, Firefox and Edge leave it alone. Either way, tar -xf opens what you have:
tar -xf Runner.app.tar # Safari unpacked the gzip for you
tar -xzf Runner.app.tar.gz # everywhere else
If you want to be certain the bytes are intact, every download carries an X-Artifact-SHA256 header with the checksum of the file as we stored it.
05“No profiles were found” and friends
Signing has its own page — see code signing & TestFlight for the table of Xcode's signing errors and what each one really means. The one worth repeating here: if your app has an extension or a widget, you must list its profile too, and the error will name the extension's bundle id, not the app's.
06The log is cut off
Logs stop at 20 MB. Anything past that is dropped and the log says so. This is almost always Xcode's default verbosity rather than anything being wrong:
- xcodebuild -quiet ... # Xcode
- flutter build ios --no-codesign # already quiet
- npm install --silent # npm
If you genuinely need the full output, write it to a file and collect it as an artifact instead:
script:
- xcodebuild ... > build.log 2>&1 || (tail -100 build.log; exit 1)
artifacts:
- build.log
07Queued and not starting
Builds wait when every machine is busy. The dashboard shows your position. Two things that are not a queue problem:
- 50 queued builds at once is the per-account cap. Past it we refuse new ones rather than let one repository's push loop starve every other project you have.
- A build that says pending for a long time with an empty queue is usually a payment problem, not a capacity one. Check for a banner on your dashboard.
08Test reports do not appear
The tests section takes JUnit XML. Most tools do not emit it by default; check your command is actually writing the file, with ls -la before the build ends.
The limits: up to 40 report files, 8 MB total, and the first 50 failures are shown in detail. A suite that blows past 50 failures is telling you something the 51st message would not add.
Remember the || true pattern — if your test command fails the build immediately, the step that converts its output to JUnit never runs.
09Something is different about the machine each time
It is. Every build gets a machine created from the same image seconds earlier, and that machine is destroyed afterwards. Nothing carries over: not caches, not files in /tmp, not installed packages, not a keychain.
That is a deliberate trade — it means a build cannot be poisoned by a previous one, and it means a customer's credentials cannot outlive their build. It also means any caching you want has to be inside your repository or fetched during the build.
10Still stuck
Two things make support fast: the build URL, and what you expected to happen. We can read the log, the machine's side of it, and the exact command we ran, which is usually enough to answer without a round trip.
If the build fails in a way you cannot see from the log, turn on Debug on failure for the repository on the Repositories page, or press Keep this machine if the build fails while a build is still running. The machine is held open for 15 minutes after a failed build and you get a terminal on it in your browser — the same machine, in the state it failed in.