Manatee

QuickTime says the file isn't compatible: what to do

· 6 min read

“The file isn’t compatible with QuickTime Player” means QuickTime understood enough of the file to know it cannot decode what is inside. It is not a corruption message. Usually the video or audio codec, or the container itself, is one Apple’s frameworks do not support, and the fix is to convert the file to H.264 or HEVC in an MP4 or MOV container. A damaged file produces a different error, and the end of this post explains how to tell the two apart.

What the message actually means

QuickTime Player relies on the same system frameworks as Finder previews, Photos, iMovie, and Safari. Those frameworks support a specific set of containers (MP4, MOV, M4V, and a few legacy formats) and a specific set of codecs (H.264, HEVC, ProRes, Motion JPEG, MPEG-4 Part 2 in some cases, AAC, ALAC, PCM, and a few more). Anything outside that set triggers the compatibility error, even if the file is pristine.

On older versions of macOS the wording differs slightly (“The document could not be opened. The file isn’t compatible with QuickTime Player” or “A required codec isn’t available”). The cause is the same.

The usual suspects

Work down this list; one of these is almost always the explanation.

  1. The container is not one Apple reads. MKV, WebM, FLV, WMV, and most AVI files fall here. Nothing inside matters, because QuickTime stops at the wrapper. See MKV file won’t open on Mac for the most common case.
  2. The video codec is unsupported. VP8 and VP9 (common in WebM and screen recordings from web apps), AV1 (only decodable on recent hardware and software), DivX and Xvid, MPEG-2 from DVDs and older camcorders, and many proprietary camera codecs.
  3. The audio codec is unsupported. An MP4 with H.264 video and DTS, FLAC, Opus, or Vorbis audio will fail, and the error message does not say that it is the audio. This catches a lot of people.
  4. The file has the wrong extension. A WebM renamed to .mp4, or an MKV renamed to .mov, gets exactly this error. Extensions are labels, and QuickTime looks at the actual structure.
  5. The file is an Apple format your Mac cannot decode yet. ProRes RAW and some 4:4:4 ProRes variants need recent hardware or Final Cut Pro’s components. Rare outside professional workflows.
  6. The file is damaged in a way that corrupts the codec header. Uncommon, but a damaged file occasionally produces the compatibility error rather than the damage error.

Find out what is inside

If the file opens in any other player, that player can usually show you the codecs. Most have a “media information” or “codec” panel. Write down the container, the video codec, and the audio codec.

If no other player opens it and you are comfortable in Terminal, file /path/to/video often identifies the real container regardless of extension. If you have ffmpeg installed, ffprobe /path/to/video lists every stream with its codec.

If neither is an option, skip ahead. The conversion step works without knowing the details, because a converter inspects the file itself.

Convert it to something QuickTime plays

The durable fix is an MP4 with H.264 video and AAC audio. It plays on every Mac, every iPhone, every Windows machine, every browser, and every chat app. HEVC is a fine alternative for your own use on Apple hardware, but H.264 is the safer choice for anything you will share. H.264 vs HEVC goes into the trade-offs.

To convert with Manatee:

  1. Open Manatee and choose Convert. The first 24 hours include every feature at no cost, with no card or email.
  2. Drop the file in (or drag it onto the menu bar icon, or right-click it in Finder and pick Fix with Manatee).
  3. Select MP4 as the target. Choose MOV instead if the file is going into iMovie or Final Cut Pro.
  4. Wait for the job to finish. If the video codec was already H.264 or HEVC, the video stream is copied and only the audio or container changes, so the job is fast and the picture is unchanged. Otherwise the video is re-encoded.
  5. Open the new file, written alongside the original.

Manatee accepts 122 input types, including every container and codec listed above, and everything runs on the Mac. The original is never modified.

Telling compatibility apart from corruption

What you see Likely cause
“The file isn’t compatible with QuickTime Player” Unsupported codec or container
“The movie could not be opened” or “The file may be damaged” Structural damage
Opens, shows 0:00 duration, will not play Missing index (damage)
Opens, plays audio, black picture Unsupported video codec, or damaged video stream
Plays, then freezes at the same spot Localized damage
A second player plays it fine Compatibility, not damage

If the evidence points to damage, a conversion will fail or produce a broken output. Repair first. Manatee’s Repair mode rebuilds damaged video containers; see How to repair a corrupted MP4 for that process. If you are unsure which you have, the second-player test above settles it in under a minute.

Questions

Why does the same file play on my iPhone but not in QuickTime on my Mac? Usually because the iPhone is using a third-party app with its own decoders, or because the file is HEVC with a profile your Mac’s macOS version lacks. Why some videos play on iPhone but not on Mac lists the combinations.

Is there a codec pack I can install for QuickTime? Not anymore. The plug-in system that allowed third-party codecs was retired years ago. The options now are a different player or a conversion.

Will converting lose quality? If the video is already H.264 or HEVC and only the container or audio was the problem, no; the video stream is copied as is. If the video must be re-encoded (VP9, AV1, DivX, MPEG-2), there is a modest loss that is not noticeable at a normal bitrate.

The file plays in a browser but not in QuickTime. Why? Browsers ship their own decoders for VP8, VP9, AV1, Opus, and Vorbis, which is exactly the set QuickTime lacks. WebM files from the web are the classic example. Converting to MP4 solves it permanently.