First-build troubleshooting¶

The failures people actually hit on their first build, and what each one means.

Upload problems¶

The signed `PUT` fails with 400 `MissingRequiredHeader`¶

While we offer build hosting, what we are good at is software, not building up server racks full of hard drives. For your build storage, we depend on Microsoft Azure, since they are good at that. If you see this error when uploading a build, that error comes from Azure Blob Storage, not AppGantry: the signed upload URL points straight at storage, and Azure requires the request to declare the blob type. Add the header:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H 'x-ms-blob-type: BlockBlob' \
  --data-binary @app.ipa

Two related mistakes produce confusing failures at the same step:

Sending your AppGantry Authorization header on the PUT. Don't — the signature in the URL is the credential.
Sending the PUT to the API host instead of the URL returned by initiate. There is no multipart upload route.

See Uploading a build.

The upload URL stopped working part-way through¶

A pending upload and its signed URL are valid for 1 hour. A slow link plus a large artifact can outrun that. Start the upload again: the abandoned pending row and any orphaned bytes are cleaned up automatically, and nothing is billed for an upload that never completed.

Re-initiating with the same version and build number may be refused with 409 first, so give the retry a new build number (or a new version name), or wait. The abandoned pending row keeps claiming that build identity until the cleanup sweep removes it, and it is swept only after it expires, so the identity can still be taken even though no build was ever created. A 409 there does not mean the build is there: see Errors → 409 when initiating a build upload.

"Payload too large"¶

Build artifacts on the Teams subscription level are capped at 500 MiB. The size is checked on the stored blob when you complete the upload, so an oversize artifact is rejected at the completion step even though the bytes went straight to storage. Trim the artifact or contact us if you have a real case for a larger cap.

"Too many pending uploads"¶

A project may hold 25 pending uploads at a time, and initiating one more is refused with 429 rate_limit_exceeded. That normally means a CI job is initiating uploads it never completes. Fix the completion step, then wait for the expired rows to be swept up, or complete the outstanding uploads.

My `.aab` was rejected¶

.aab App Bundles are a Play Store publishing format, not a directly installable artifact. Upload an .apk instead — that's what AppGantry distributes to your testers.

HTTP 402 on upload¶

Your organization can't move bytes right now. The error field tells you which case you're in: an exhausted pre-paid balance, a spend cap you reached, an unpaid subscription, an ended trial, or an organization that committed to paying but has no card yet. See Errors → 402 and Billing, usage & caps.

Install problems (Apple)¶

"Unable to install" / the icon greys out on the home screen¶

Almost always a signing or provisioning mismatch:

The artifact must be signed for distribution to your testers: ad-hoc, enterprise/in-house, or another distribution profile the device trusts. A development-signed build installed through a different route is not the same thing.
For ad-hoc distribution, the device's UDID must be in the provisioning profile the artifact was signed with. Adding the device to AppGantry afterwards doesn't retroactively change what you signed: register the device, then re-sign and re-upload. See Enrolling test devices.
Check the profile hasn't expired.

Nothing happens when I tap Install¶

The itms-services:// hand-off only runs on the device itself, in Safari. A desktop browser cannot run it, and neither can most in-app webviews — a link opened inside Mail, Slack, or a QR-scanner app's own built-in browser. Reopen the page in Safari on the target iPhone or iPad and tap Install there.

Starting from a desktop is fine; you hand off to the device first. Open the install page on My apps on a desktop and it shows a QR code alongside the button: scan it with the Camera app on the iPhone or iPad you want to install on, and it opens a short-lived install page in Safari where you tap Install. Scan it with the Camera app rather than with a QR-scanner app, so the page opens in Safari instead of that app's webview. Android's install page offers the same hand-off — the QR there downloads the .apk straight to the phone.

The install link worked yesterday and doesn't today¶

Over-the-air install capabilities are deliberately short-lived (about 15 minutes). Go back to the tester portal and start the install again; it mints a fresh one. Don't bookmark or share the resolved manifest URL.

The tester can't see the app at all¶

Check, in order:

Are they signed in with the email address you invited?
Is the grant still pending (they haven't signed up or verified their email yet)?
Did you grant at the level you think you did? Organization, project, and channel grants are separate. The tester's channel list shows how each grant was made.
Is the release disabled, rolled back, or the build revoked?

Install problems (Android)¶

The download finishes but the install doesn't start¶

Android blocks installs from unknown sources by default. The tester has to allow installs from the browser they downloaded with, then open the downloaded .apk again.

"App not installed"¶

Usually a signature mismatch with an already-installed copy of the same package, or a downgrade. Uninstall the existing copy and try again.

Account and access problems¶

"Verify your email before performing this action"¶

New accounts must verify their email before doing anything state-changing. Read-only calls keep working. Resend the verification email from Account settings or the Check your email page.

My CI token gets 401 but the web app works¶

Project access tokens and browser sessions are independent credentials. Check that the token hasn't expired or been revoked, that you're sending it as Authorization: Bearer ag_prj_…, and that the organization and project you're addressing match the token's binding.

My CI token gets 403 on a route the web app allows¶

Some surfaces deliberately refuse long-lived tokens: account-level settings, token management itself, and organization storage configuration all require an interactive sign-in. See Authorization.

Still stuck?¶

Two places are worth checking before you write to anyone:

FAQ — the same ground as short answers, and it covers a good deal more than a first build.
Feature availability — whether the thing you're trying to do has actually shipped, and whether your plan gates it.

Then email support with the organization and project identifiers (both are on the respective Settings pages and neither is a secret), the build identifier if you have one, and the error code and message from the response. Don't send tokens.