USDZ not working in Quick Look: the ten real causes

First, split the problem in two

Almost every "USDZ not working" report is one of two very different things: the archive never opened (packaging or delivery), or the archive opened and rendered incorrectly (content). They have no overlap in fixes, so establish which one you have before changing anything. If you get a blank AR view, a spinner, or an immediate bounce back to Safari, you are in the first category.

Packaging failures — the archive is not a valid USDZ

USDZ is not "a zip with USD in it". The USDZ specification is strict, because the format is designed to be memory-mapped and read in place: "A usdz package is a zero compression, unencrypted zip archive", the data for each file must "begin at a multiple of 64 bytes from the beginning of the package", and "the first file in the package must be a native usd file".

• Deflated entries. Zipping a folder with zip or Finder produces compressed entries. That violates the spec. Use usdzip, Reality Converter, or another USDZ-aware packer.
• Misaligned entries. Same cause, same fix — general-purpose zip tools do not pad to 64 bytes.
• No default stage first. If the first entry is a texture, there is nothing for the viewer to open.
• Disallowed payloads. The spec permits usda/usdc/usd, png/jpeg/exr/avif images, and M4A/MP3/WAV audio. A stray .tga or .psd inside the bundle is not a USDZ asset.

Delivery failures — the file is fine, the server is not

WebKit's guide to AR assets in Safari documents two requirements people routinely miss. The file must be served with the MIME type `model/vnd.usdz+zip` — a .usdz served as application/octet-stream may simply download instead of opening AR. And the markup matters:

<a rel="ar" href="/models/chair.usdz">
  <img src="/models/chair-poster.jpg" alt="Oak dining chair">
</a>

Adding rel="ar" stops Safari navigating away and jumps straight into the AR view. The anchor must contain a single child that is an img or picture element — an anchor wrapping a div, or one with no child at all, does not get the AR treatment. Object URLs created with URL.createObjectURL() are another known trap: with no .usdz extension in the URL, Quick Look can bail out immediately.

"This file is too large to open in Quick Look"

This message is about memory, not bytes. Developers have reported it on files as small as 1.6 MB, because what Quick Look measures is the in-memory footprint needed to display the model — decoded textures plus geometry — not the size on disk. A handful of 4096 × 4096 maps can occupy well over a hundred megabytes once decoded, regardless of how well they compressed.

Content failures — it opened, but it is wrong

1. Missing textures. A USDZ is a self-contained bundle. If the stage references @./textures/albedo.png@ and that file is not in the archive, the reference dangles and the surface renders black, white or flat-tinted. Absolute paths from the authoring machine are the usual cause.
2. Unsupported texture encodings. 16-bit-per-channel PNGs and paletted (colour type 3) PNGs are widely reported to render black or be skipped on iOS; progressive JPEGs are similarly unreliable, where baseline JPEG is not. Re-encode as 8-bit truecolour PNG or baseline JPEG.
3. Nothing to render. A stage with no mesh geometry opens successfully and shows an empty scene — common after a failed conversion that produced a valid but empty stage.
4. Wrong scale. If the stage declares metersPerUnit other than 1, a centimetre-authored asset can appear 100× too large. Safari 27 explicitly shipped a fix for <model> elements "displaying at 100x the expected size for assets authored in tools that use centimeter units".
5. Wrong orientation. Quick Look assumes Y-up. A Z-up stage lands on its side.
6. Materials that USDZ cannot carry. Glass authored with KHR_materials_transmission becomes opaque; KHR_materials_volume, clearcoat, sheen, iridescence and anisotropy all degrade. That is a conversion problem, covered in glTF to USDZ converter issues.

A five-minute triage

1. AirDrop the .usdz straight to an iPhone and tap it. If it opens there but not on your site, the problem is delivery (MIME type, markup, URL), not the file.
2. If it fails on-device too, unzip it and check: is the first entry a .usd/.usdc/.usda? Are the entries stored rather than deflated? Is every referenced texture present?
3. If it opens but shows nothing, check for geometry in the stage.
4. If it opens at absurd size, check metersPerUnit; if it is on its side, check upAxis.
5. If it opens and the materials look flat, list the glTF extensions in the source and expect to bake them.

Every one of those checks except the last is mechanical — and mechanical checks are worth automating, because you will run them on every SKU. What no tool can do is promise you a device-accurate render: Apple exposes no headless Quick Look or RealityKit renderer, so structural conformance is the honest ceiling for any validator, ours included. For high-value products, still look at it on a phone. Related: Safari 27 `<model>` requirements.