Troubleshooting

Fix “Safari cannot download this file” for PKPass

Diagnose the common packaging, signature, MIME type, redirect, and certificate problems that prevent Apple Wallet passes from installing.

By Swapnanil DholUpdated August 13, 20267 min read

What you’ll leave with

Validate the exact bytes downloaded from the production URL.
Serve .pkpass over HTTPS with application/vnd.apple.pkpass.
Most opaque Safari failures become actionable once the archive and signature are inspected separately.

Start with the production response

Download the pass from the same URL Safari opens and save the response without modification. Do not validate a local source file while assuming the server returns identical bytes. Authentication middleware, redirects, HTML error pages, compression, and storage transformations can all change the response.

Confirm the request finishes with a successful status, the body is a ZIP-based .pkpass rather than HTML or JSON, and redirects do not land on an inaccessible or non-HTTPS endpoint.

curl -L -D headers.txt   -o downloaded.pkpass   https://example.com/passes/member-42.pkpass

file downloaded.pkpass
unzip -l downloaded.pkpass

Check MIME type and delivery headers

Serve a single pass as application/vnd.apple.pkpass. Use a sensible .pkpass filename in Content-Disposition when the response is treated as a download. Avoid serving the file through a generic text or JSON handler.

HTTPS must be valid on the final URL. If a CDN or object store sits in front of the application, verify its metadata because it may override the origin Content-Type. Also check that a service worker is not replacing the response with an offline page.

Content-Type: application/vnd.apple.pkpass
Content-Disposition: attachment; filename=member-42.pkpass
No HTML login page, WAF challenge, or expired signed URL
No byte transformation after the package was signed

Inspect package structure and manifest coverage

Open the archive and confirm pass.json, manifest.json, signature, and required image assets are at the root. An extra wrapper folder is a common cause of rejection. Remove .DS_Store and __MACOSX entries before rebuilding the manifest.

Parse pass.json as JSON, check required identifiers, and recompute every manifest digest. A missing manifest entry or stale digest means the signature may be cryptographically valid for a manifest that no longer describes the files in the archive.

Verify signature, certificates, and identity

Verify the detached PKCS#7 signature against the exact manifest bytes. Then inspect whether the signing certificate and embedded WWDR certificate are in date, the chain links correctly, and the Pass Type ID certificate was issued for the identifiers inside pass.json.

After fixing any issue, rebuild in this order: finalize files, generate manifest, sign manifest, create archive, validate archive, then redownload it from production. This prevents a corrected file from being paired with a stale manifest or signature.

Put it into practice

Build the JSON, then verify the package.

Use the free browser tools to turn the rules in this guide into a clean starting file and an actionable validation report.

Open JSON Builder Open PKPass Validator

Skip the hand-assembly.

PassMaker does every step on this page on your iPhone — field editor, artwork, manifest, PKCS#7 signing and Add to Wallet — without wiring up a signing environment.

Download on the App Store