Skip to main content
Building, signing, and binary uploads Level: Intermediate 11 min read

Tracking App Store Upload Progress and Chunk Status in Real Time

How to track App Store binary upload progress, understand multipart chunking, diagnose network interruptions, and check container processing states.

Published: 2026-11-02 • Last Updated: 2026-11-02 • Author: Kip Lawrence
Key MCP Tools: build_upload_status

Overview: The Stages of Binary Transfer to Apple

Uploading a 300 MB iOS application package (.ipa) or a 1.2 GB macOS installer (.pkg) to App Store Connect is rarely a simple single-request file upload. Apple's modern asset delivery pipeline relies on multipart chunking, presigned cloud storage endpoints, and server-side ingestion validation.

When an upload appears stalled or fails midway, developers must determine where in the pipeline the operation stopped: did a network socket drop during chunk transfer, did an Apple presigned storage token expire, or did Apple's ingestion engine reject the binary during server-side unpacking?

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                        BINARY DELIVERY TIMELINE                        │
│                                                                        │
│   [ Stage 1: Local Inspection ]  ──► SHA-256 Hash & Metadata Verified   │
│                 │                                                      │
│                 ▼                                                      │
│   [ Stage 2: Asset Reservation ] ──► POST /v1/buildUploads             │
│                 │                    Returns chunk uploadOperations    │
│                 ▼                                                      │
│   [ Stage 3: Part Streaming ]    ──► Sequential HTTPS PUTs to Storage  │
│                 │                    Chunk 1 ... Chunk N               │
│                 ▼                                                      │
│   [ Stage 4: Asset Finalization] ──► PATCH /v1/buildUploadFiles        │
│                 │                    uploaded: true + MD5 Hash         │
│                 ▼                                                      │
│   [ Stage 5: Ingestion & Status] ──► build_upload_status               │
│                 │                    Checks container COMPLETE / FAILED│
│                 ▼                                                      │
│   [ Stage 6: Build Processing ]  ──► builds_list / build_get           │
│                                      Apple validates binary for use    │
└────────────────────────────────────────────────────────────────────────┘

This guide explains how Apple's multipart chunking works, what progress data FlightDeck's MCP tools can inspect, how retries and cancellations are handled, and how to diagnose interrupted transfers.


1. Understanding Multipart Chunking in App Store Connect

When FlightDeck or Xcode registers a binary with App Store Connect (POST /v1/buildUploadFiles), Apple returns an array of uploadOperations.

Each operation corresponds to a specific byte slice of your application binary:

JSON
[
  {
    "method": "PUT",
    "url": "https://store-01.apple.com/part-1?Signature=...",
    "length": 52428800,
    "offset": 0,
    "requestHeaders": [
      { "name": "Content-Type", "value": "application/octet-stream" }
    ]
  },
  {
    "method": "PUT",
    "url": "https://store-01.apple.com/part-2?Signature=...",
    "length": 52428800,
    "offset": 52428800,
    "requestHeaders": [
      { "name": "Content-Type", "value": "application/octet-stream" }
    ]
  },
  {
    "method": "PUT",
    "url": "https://store-01.apple.com/part-3?Signature=...",
    "length": 20971520,
    "offset": 104857600,
    "requestHeaders": [
      { "name": "Content-Type", "value": "application/octet-stream" }
    ]
  }
]

Why Apple Uses Chunking:

  1. Reliability on Large Binaries: If network connectivity drops during a 1 GB transfer, only the affected 50 MB chunk needs to be retried, not the entire archive.
  2. Ephemeral Presigned URLs: Each chunk URL contains a short-lived authorization signature granting write access only to that specific slice.
  3. Bandwidth Optimization: Allows Apple's distributed storage tier to receive byte streams concurrently or across multiple edge locations.

2. Progress Tracking Boundaries: MCP vs Local Runtimes

Understanding what progress information is available requires distinguishing between the local transfer engine and the MCP query interface:

In-Flight Streaming Progress (Local Runtime)

During an active upload executed by FlightDeck, the internal BuildUploadService tracks byte streaming progress in real time via in-process progress callbacks:

  • Total bytes uploaded vs total binary file size (bytesUploaded / totalBytes).
  • Current part index and total parts (e.g., Part 3/7).
  • Real-time transfer speed (bytesPerSecond computed from elapsed time).
  • Estimated time remaining (estimatedRemaining computed from current speed).
  • Stale-file and mid-stream integrity validation: If the local binary on disk is modified, truncated, or recompiled while bytes are streaming, FlightDeck detects a hash or size discrepancy and raises a MID_STREAM_INTEGRITY_VIOLATION, aborting the transfer immediately.
Note

MCP Client Notification Boundary: Standard JSON-RPC Model Context Protocol (MCP) clients communicate with FlightDeck over sequential stdio sessions. FlightDeck's in-flight byte-progress callbacks directly update the FlightDeck Desktop GUI. MCP clients do not receive continuous streaming progress events over stdio; invoking build_upload_start returns synchronously once the upload and initial ingestion handshake complete or fail.

Server-Side Status Tracking (build_upload_status)

Once chunks are transferred or while an upload container exists on Apple servers, an AI coding assistant queries Apple's server-side container status using build_upload_status:

  • State: Whether the Apple container is PROCESSING, COMPLETE, or FAILED.
  • Created Build ID: The assigned Apple build resource ID once ingestion completes.
  • Server Errors: Any rejection notices emitted by Apple's ingestion tier (such as invalid archive structure, missing icons, or malformed plist entries).
Important

Upload Complete vs Processing Complete: An upload container reporting COMPLETE means Apple's object storage has successfully received and assembled all binary slices. It does NOT mean the build is ready for testing. Apple's internal build processing pipeline (symbol extraction, virus scans, App Store validation) runs asynchronously after ingestion. Apple provides no fixed SLA or processing duration guarantee; processing times vary depending on Apple queue depth, server load, and binary complexity.


3. Retries, Resumability, and Cancellation

Network interruptions during multi-gigabyte uploads are common. FlightDeck manages errors according to strict protocol rules:

Transient Part Retries (Live Session)

If an individual chunk upload fails due to a transient network glitch, TCP socket reset, or HTTP 5xx server error, FlightDeck's PresignedStorageTransport automatically retries that specific slice:

  • Up to 3 automatic retries for the failing part.
  • Exponential backoff starting at 500 ms.
  • Completed chunks are not re-sent.
  • HTTP 4xx client errors (such as expired presigned signatures or authorization failures) abort immediately without retry.

Resumability Across Application Restarts

FlightDeck streams chunks directly from disk and verifies integrity in memory. To prevent state inconsistency and avoid persisting sensitive presigned URLs or partial chunk tokens to disk, FlightDeck does not persist partial chunk state across application restarts. If an upload is terminated (by closing the application, restarting your Mac, or killing the process), resuming requires initiating a new upload session (build_upload_start), which reserves a fresh container with Apple.

Cancelling an Upload (build_upload_cancel)

If an upload was initiated with an incorrect version number, was aborted, or is stalled on Apple servers, you can delete the uncommitted BuildUpload container on Apple's servers using build_upload_cancel. This invokes Apple's canonical buildUploads_deleteInstance operation to release the container and clean up orphaned asset reservations.


4. Diagnosing Upload State with AI Prompts

When you need to determine whether an upload is in flight, has stalled, or has completed, use this structured diagnostic prompt with your AI assistant:

MARKDOWN
Help me determine whether the latest App Store upload for "Quest Companion" is still transferring, has failed, or has completed and entered Apple's processing stage. Inspect available local upload logs and use FlightDeck to check App Store Connect build status. Clearly identify which stage is confirmed and which information is unavailable.

What Your AI Assistant Does:

  1. Checks whether local build or export logs in your project indicate an ongoing upload process.
  2. Calls FlightDeck's build_upload_status if a buildUploadId is available from an active session.
  3. Calls FlightDeck's builds_list for your application to determine whether Apple has already registered the build.
  4. If a build record is found, reports its exact processingState (PROCESSING, VALID, or FAILED).

5. Troubleshooting Common Upload Stalls and Failures

1. Signature expired (HTTP 403 on presigned URL)

  • Cause: Network latency was so severe that Apple's ephemeral presigned URL expired before the chunk finished uploading (Apple storage URLs typically expire after 15 to 30 minutes).
  • Fix: Start a new upload session on a stable, high-speed connection.

2. MID_STREAM_INTEGRITY_VIOLATION

  • Cause: The binary file on disk was modified, recompiled, or overwritten while FlightDeck was streaming bytes to Apple.
  • Fix: Ensure build scripts do not run concurrently with upload operations. Wait for export commands to finish before initiating build_upload_start.

3. Apple BuildUpload failed: ITMS-90034 / Missing Info.plist

  • Cause: The package transfer completed, but Apple's container ingestion rejected the archive structure upon decompression.
  • Fix: Run FlightDeck's build_upload_preview locally before uploading to catch structural archive errors in advance. See Pre-Upload Binary Validation Checks.

4. Build uploaded but not appearing in TestFlight

  • Cause: The binary transfer succeeded, but the build is currently in Apple's server-side processing queue.
  • Fix: Monitor build processing using Checking Build Processing State.

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store