Validate and upload altool Transporter App Store Connect API and ITMS error catalogue
Parent: macOS App Testing and Release QA · Published reference · snapshot 2026-10-02
↓ Facts as markdownall context files
Source-anchored research for Validate and upload altool Transporter App Store Connect API and ITMS error catalogue. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- The App Store Connect build-upload API is a 4-step flow: POST BuildUploads (bundle version, platform), POST BuildUploadFiles (file name, size, asset type) returning PUT upload operations with headers and chunks, upload the chunks, then PATCH uploaded=true; state moves PROCESSING to COMPLETE and a webhook can signal it. macOS is a listed platform. (high confidence) (verified as of 2025-06-01) [source]
- After upload the build is processed and Apple emails when processing completes; processing-time validation failures arrive by email, so a successful altool/Transporter upload does not guarantee a usable build. (medium confidence) [source]
- ITMS-90296 'App Sandbox not enabled' reads: executables must include com.apple.security.app-sandbox = true. In one Nov 2024 case the root cause was AppleDouble ._* files / __MACOSX dirs and xattrs breaking the signature, not a missing entitlement. Check with codesign --verify -vvv and codesign --display --entitlements - on the .app before packaging. (medium confidence) [source]
- ITMS-90238 'Invalid Signature' occurs when a Developer ID-signed (notarized) app is submitted to the Mac App Store. Mac App Store builds need '3rd Party Mac Developer Application' signing and a '3rd Party Mac Developer Installer' signed pkg; keep a separate build for Developer ID. (low confidence) [source]
Problems, failure modes and limitations
- altool --validate-app preflights an archive; --upload-app is deprecated in favour of --upload-package. --type macos is a supported platform value; notarization is no longer supported by altool (use notarytool). (high confidence) (verified as of 2025-09-23) [source]
- altool API-key auth uses --apiKey and --apiIssuer; it looks for AuthKey_<key>.p8 in ./private_keys, ~/private_keys, ~/.private_keys, ~/.appstoreconnect/private_keys, or $API_PRIVATE_KEYS_DIR. Password sources can be plaintext, @keychain: or @env:. --output-format accepts xml, json, normal; exit code is 0 on success, 1 on failure. (medium confidence) [source]
- Transporter CLI (iTMSTransporter) uploads a macOS app with -m upload -assetFile app.pkg; -f cannot be used for apps and .itmsp delivery of apps is deprecated. Auth is -u/-p, -jwt, or -apiKey/-apiIssuer; -u/-p cannot be combined with the other two. -v controls verbosity (eXtreme default). (high confidence) (verified as of 2025-09-03) [source]
- iTMSTransporter 4.1.x failed with 'ERROR: No value present' when using -jwt with -assetFile/-assetDescription starting around 30 Sep 2025; 4.0 and -apiKey/-apiIssuer worked. Apple gave no official response in the thread. (low confidence) (verified as of 2025-09-03) [source]
- With Xcode 26 altool, fastlane routed uploads through deprecated --upload-app and hit HTTP 409 on CREATE BUILD when several apps share a bundle ID prefix; workaround was --use-old-altool via DELIVER_ALTOOL_ADDITIONAL_UPLOAD_PARAMETERS. Treat as a pin-and-test hazard for release scripts. (low confidence) (verified as of 2025-09-23) [source]
Comparisons and alternatives
- Release-script pattern: run altool --validate-app (or Transporter verify) on the signed pkg, upload with an API key rather than an Apple ID password, capture --output-format json and the ITMS code, then confirm processing by email or API state before TestFlight. (low confidence) [source]
Facts and statements
- Apple lists four upload methods for builds: Xcode, Transporter (macOS app), altool via xcrun (validation and upload), and the App Store Connect API using JWTs. (high confidence) [source]
Children
- No children recorded.