A Fastlane upload IPA error usually falls into one of a few categories, and authentication is the most common. Because Apple accounts use two-factor authentication, Fastlane cannot upload with your plain password; it needs either an App Store Connect API key, which is the recommended option for automation, or an app-specific password. Other frequent causes are a duplicate binary from reusing a version and build number, an invalid binary from a signing or compliance issue, or the app not being found because the bundle identifier does not match. Identify which category your error is in, and the fix follows: fix the credential, bump the build number, or correct the binary.
Short answer
Most Fastlane upload errors are authentication, a duplicate build, or an invalid binary, so identify the category first. Per Fastlane's authentication guide, two-factor accounts cannot upload with a plain password; use an App Store Connect API key, which is recommended for CI, or an app-specific password through the relevant environment variable. Per Fastlane's upload_to_testflight action, a duplicate version and build number is rejected, so bump the build number. Fix signing, export compliance, or missing assets for an invalid binary, and confirm the bundle identifier matches an existing app record. Match the fix to the category rather than retrying blindly.
Authentication errors: API keys versus app-specific passwords
Authentication is the most common Fastlane upload failure, because Apple requires two-factor authentication and Fastlane cannot complete a two-factor challenge with a plain password. You have two supported ways to authenticate an upload: an App Store Connect API key, or an app-specific password. Supplying your normal Apple ID password results in an authentication error, so one of these two is required.
The two suit different situations. The App Store Connect API key is the more robust choice, especially for continuous integration, because it uses a key file rather than a password and does not trigger two-factor prompts. An app-specific password works for the upload path and is simpler to set up for a one-off local run. Both are valid, but for automation the API key avoids the session and two-factor issues that make app-specific passwords fragile in CI.
App Store Connect API key
The App Store Connect API key is the recommended way to authenticate Fastlane uploads. You create the key in App Store Connect, which gives you a key ID, an issuer ID, and a downloadable key file, and you configure Fastlane to use those. Because it is designed for programmatic access, it authenticates without your personal password and without triggering two-factor prompts, which makes unattended uploads far more stable.
Set it up once and reuse it across your pipeline. Store the key file and its identifiers securely in your CI secrets, configure Fastlane's App Store Connect API key action, and your upload steps authenticate through it. The initial setup is slightly more involved than an app-specific password, but for any automated upload it is worth it, because it removes the recurring authentication and session failures that otherwise interrupt builds.
App-specific passwords and sessions
An app-specific password is the alternative, generated from your Apple ID account page and supplied to Fastlane through its app-specific-password environment variable. It lets the upload authenticate on a two-factor account without an interactive second factor, and it is the quickest option for a local upload. Store it as a secret, since it grants upload access to your account.
Where app-specific passwords get fragile is in longer or interactive Fastlane flows that use a Spaceship session, which can expire, producing session errors on CI. When you see repeated session or two-factor problems in automation, that is the signal to move to the App Store Connect API key, which does not rely on a session. For the plain upload path, an app-specific password is fine, but the API key is the more durable choice when sessions are involved.
Non-authentication upload errors
Not every upload error is about credentials. A frequent one is a duplicate binary: Apple rejects an upload that reuses the same version and build number as an existing build, so if you see a duplicate or already-used error, bump the build number and re-upload. This is a common trip-up when re-running a build without incrementing the number.
Others relate to the binary itself. An invalid binary can come from a signing problem, a missing export-compliance declaration, or missing required assets like icons, each of which surfaces during upload and is fixed in the build rather than the upload command. And an app-not-found error usually means the bundle identifier does not match an app record in App Store Connect, so confirm the identifier and that the app record exists. Reading the specific error tells you which of these applies, since the message almost always names the binary problem or the missing record directly.
Common errors at a glance
Matching the error to its category speeds the fix. The table below pairs common Fastlane upload errors with their causes and fixes.
| Error | Likely cause | Fix |
|---|---|---|
| Authentication failed | Two-factor account, wrong credential | Use an App Store Connect API key or app-specific password |
| Session expired | A Spaceship session lapsed on CI | Switch to the App Store Connect API key |
| Duplicate or used binary | Reused version and build number | Bump the build number and re-upload |
| Invalid binary or ITMS error | Signing, compliance, or missing assets | Fix the build, then re-upload |
| App not found | Bundle identifier does not match a record | Match the identifier to the app in App Store Connect |
Read the table against the exact error text. Authentication and session errors point to the credential and, for CI, the API key, while duplicate and invalid-binary errors point at the build itself.
Fix checklist
Working through the categories in order resolves most upload errors. The checklist below covers the steps.
| Check | Action | Done? |
|---|---|---|
| Use an API key | Configure the App Store Connect API key for CI uploads | [ ] |
| Or an app-specific password | Supply it via the Fastlane environment variable | [ ] |
| Bump the build number | Avoid a duplicate binary rejection | [ ] |
| Validate the binary | Fix signing, compliance, and required assets | [ ] |
| Retry the upload | Re-run the upload after the fix | [ ] |
The step that prevents the most recurring failures is using the App Store Connect API key for automated uploads, since it removes the authentication and session problems that dominate these errors. For the build-side errors, bump the build number and fix the binary before retrying the upload command.
After upload: scan before you submit
Fixing the upload gets your build to App Store Connect, but a build that uploads cleanly still has to pass review, and a preventable security or privacy issue can cause a rejection unrelated to how you uploaded. Those issues are cheaper to catch before submission than after.
A scanner like PTKD.com analyzes your .ipa and reports findings ordered by severity and mapped to OWASP MASVS, so you catch issues like unjustified permissions, cleartext traffic, or embedded secrets before you submit. To be clear about the boundary: PTKD does not manage your credentials, configure an API key, or upload your build. It checks the uploaded build's security, which is a separate concern from the upload itself.
What to take away
- Most Fastlane upload errors are authentication, a duplicate build, or an invalid binary, so identify the category first.
- Two-factor accounts cannot upload with a plain password; use an App Store Connect API key, recommended for CI, or an app-specific password.
- The App Store Connect API key avoids two-factor prompts and session errors, making it the most reliable choice for automated uploads.
- A duplicate binary needs a bumped build number, and an invalid binary needs a signing, compliance, or asset fix in the build.
- After the upload succeeds, scan your build with PTKD.com for the security issues a clean upload does not address.
