Observed Symptoms & Error Messages
Users encountering this problem typically observe one or more of the following behaviors when running AirCard on macOS:
- Clicking "Apply" or "Flash" initiates the operation, but the progress bar stops moving at exactly 25%.
- The AirCard application window becomes unresponsive or displays a beachball cursor on macOS.
- The iPhone display remains active, but no visual update occurs in Apple Wallet.
- Disconnecting the cable displays an abrupt cancellation error.
Confirmed Technical Context
Discussed in GitHub Issue #70. Primarily reported by users attempting to flash non-standard image formats (e.g. transparent webp converted to png, CMYK color spaces, or passes with active NFC transit locks).
Step-by-Step Diagnostic Checklist
Work through the following checklist in sequence. Each step is designed to be safe, reversible, and targeted toward identifying the exact point of communication failure:
Cancel the Stuck Session and Force Quit if Necessary
Safe & ReversibleIf the progress indicator has remained motionless at 25% for more than two minutes, the process will not recover automatically. Press Cmd + Option + Esc on your Mac, select AirCard, and choose "Force Quit". Do not disconnect your iPhone while quitting.
Inspect Image Color Profile & Format in Preview
Safe & ReversibleOpen your custom card artwork in macOS Preview. Press Cmd + I to open the Inspector window. Inspect the "Color model": it MUST be "RGB" (or sRGB). If it reads "CMYK" or "Grayscale", click File > Export, choose format "PNG", and ensure the color space is converted to standard sRGB. iOS CoreGraphics decoders fail on CMYK passes.
Remove Malformed Transparency or Alpha Layers
Safe & ReversibleApple Wallet passes require a solid opaque background for primary card artwork. If your artwork contains fully transparent outer regions or irregular alpha channels, open the image in an editor and flatten the graphic onto a solid background color before saving.
Verify Pass Lock Status in Apple Wallet
Safe & ReversibleOpen the Apple Wallet app on your iPhone and check the card you are modifying. If the card is an active transit pass set as an "Express Transit Card", temporarily disable Express Transit in Settings > Wallet & Apple Pay > Express Travel Card. Re-enable it only after flashing.
Relaunch AirCard and Re-apply with Validated Image
Safe & ReversibleRelaunch AirCard, select your target pass, load the re-encoded sRGB PNG, and click "Flash". Observe the progress bar: it will advance past 25%, progress through 50% and 75%, and reach 100% completion.
What the Upstream GitHub Issue Confirms
Issue #70 confirms that 25% is the stage where the desktop application hands off the image bundle to the iOS pass verification engine. If the image header is corrupt or the pass type rejects asset replacement, the iOS service fails silently without returning an error code, causing the desktop app to hang.
If the Issue Persists
If a specific card consistently hangs at 25% even with standard PNG images, test flashing a different card (such as a generic store loyalty card). If other cards succeed, the original card likely has server-side pass updates enforced by the issuer.
If you have exhausted all steps without success, you can gather non-sensitive macOS Console diagnostic messages (filter by process name usbmuxd or AirCard) and contribute your findings to the upstream issue tracker at Issue #70 on GitHub.
Technical Evidence & Verification
âś“ Verified SourceThis document adheres to the AirCardGuide factual verification policy. Conclusions, system requirements, and diagnostic procedures are confirmed against official upstream releases and technical issue discussions.