Skip to content

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

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 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 (strip bitcode/symbols, drop unused resources) 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. For a Play Store release, upload the .aab to the Google Play Console yourself, because publishing from AppGantry is not operational.

The build uploaded, but the platform is wrong

A project targets one platform, chosen at creation and fixed afterwards. Every build inherits it. If you picked the wrong one, create a new project with the right platform.

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.

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:

  1. Are they signed in with the email address you invited?
  2. Is the grant still pending (they haven't signed up or verified their email yet)?
  3. 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.
  4. 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?

Three 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 or environment gates it. Store publishing, for example, is not operational for anyone, so a failed publish job is not something you can fix.
  • Web app feature guide → If a control is missing — when the problem is a screen or button you can't find rather than an error you can read.

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.