HTML5 Video Not Properly Encoded: Causes and Fixes

by .

When you receive the notice “HTML5 video not properly encoded”, your player is unable to use the video provided. The reason could be an unsupported codec or a corrupted file; however, a single notification does not confirm faulty encoding. First, verify that the video URL and server response are correct, and that the requested file was received by your browser. If the file was delivered successfully, consider re-encoding it as an MP4 with H.264 video and AAC audio.

This tutorial applies to standard video files embedded in sites. Protected content streams and HLS/DASH players have their own additional requirements.

Quick checks: what failed?

What you findWhat to check next
The video URL returns 404, 403 or a login pageFix the path, access rules or expired URL before re-encoding.
The file plays locally but fails in a browserInspect codecs, profile, pixel format and the HTTP response.
Sound plays but the picture is missingCheck support for the video track and its encoding settings.
The picture plays without soundCheck mute settings, whether audio exists, and its codec.
Clicking Play works, but automatic playback failsInvestigate autoplay policy rather than converting the file.

What does “HTML5 video not properly encoded” mean?

In most cases, this phrase is generated by the site’s player rather than being a standard HTML error message. While HTML provides the video element, the browser must be able to interpret the container and any media within.

An MP4 is a container. H.264 is a video codec. And AAC is an audio codec. There can be two MP4 files with the same extension, yet they can be incompatible with different browsers due to differing codecs. Simply renaming a MOV file to MP4 does not convert its internal media.

MDN’s guide to web video codecs indicates that MP4 with H.264 and AAC is a broadly supported combination. It represents a good place to begin; however, the target device must also be capable of supporting the file’s profile, level and dimensions.

If you are watching someone else’s video

Try reloading the page and using an up-to-date version of your browser. If possible, view other videos on the same site, then try viewing the clip on a different device. These steps help determine if the problem exists with one file or with your browser.

If private mode works, inspect extensions and site data. Private mode changes login access as well, so compare like-for-like results. If the same clip fails across devices, contact the site owner and send them its page URL. As a viewer, you can’t repair the website’s source file by modifying browser settings.

Do not install codec packs or browser plugins suggested via popups. Install updates normally through your browser’s update mechanism and use your device manufacturer’s supported media components.

1. Check the actual video request

Using your browser’s developer tools, select Network, reload the page and press Play. Examine the media request, not just the HTML page.

  • Confirm that the request reaches the intended file without an unexpected redirect.
  • Check the response body. A login screen or error document is not playable video, even when its URL ends in MP4.
  • For MP4, check that the response has an appropriate Content-Type: video/mp4 header.
  • Compare the downloaded file’s size with the original to spot an incomplete upload.

For common file delivery, expect a successful response, commonly 200, or 206 if the server honours byte-range requests. Range support helps seeking; however, a lack of 206 does not confirm encoding faults. Check for HTTPS issues, expired signed URLs and CDN access rules as well.

Do not automatically add CORS headers. Basic cross-origin video can play without a CORS-enabled request; however, requesting via JavaScript fetch, adding a crossorigin attribute, or reading frames through canvas will alter these requirements.

2. Read the browser’s media error

Run this in the developer console after playback fails:

const video = document.querySelector("video");
console.log({
  source: video?.currentSrc,
  code: video?.error?.code,
  message: video?.error?.message
});

If the video sits within an iframe, select the iframe’s console context. Custom streaming players may provide their own diagnostic logs.

The MediaError reference from MDN defines code 2 as a network failure, code 3 as a decoding failure, and code 4 as an unsuitable source. When code 3 is returned, it is worth examining the file further. Code 4 can indicate unsupported formats or an unusable source as well; neither replaces examining the initial request. The message may be empty.

3. Inspect the file before converting it

You can inspect the local media file using ffprobe, included with FFmpeg:

ffprobe -v error -show_entries stream=codec_type,codec_name,profile,pix_fmt,width,height -of json input.mp4

Look for the codec type for audio and video tracks, pixel format and dimensions. HEVC videos can work on some devices but fail on others. H.264 video with a 10-bit or 4:4:4 pixel format may have different support from a standard 8-bit 4:2:0 export.

FFmpeg can report decoding issues when you run:

ffmpeg -v error -i input.mp4 -f null -

This decodes without saving a converted copy. Decoding issues are evidence worth investigating. A clean result does not establish browser compatibility, since FFmpeg can decode files that a specific browser cannot.

4. Re-encode an SDR video for wider compatibility

Here is a practical starting point for ordinary SDR sources when your build includes the libx264 encoder:

ffmpeg -i input.mp4 -map 0:v:0 -map "0:a:0?" -c:v libx264 -crf 23 -preset medium -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:a aac -b:a 128k -ac 2 -movflags +faststart output-web.mp4

It selects the first video track and an optional first audio track. It creates H.264 video using an 8-bit 4:2:0 pixel format, rounds dimensions down to even numbers, and converts existing audio to stereo AAC. It does not create audio when none exists in the source.

The quality setting CRF 23 is a starting point; you’ll need to review results visually and make adjustments based on your footage. Large dimensions and high frame rates can still exceed device capabilities. Reduce them when required to accommodate your audience’s hardware.

The official FFmpeg documentation for MP4 explains how +faststart moves the index to the beginning of a file, which can help playback begin sooner. It does not repair a damaged stream or make an unsupported codec usable.

Save the original file. HDR requires an appropriate workflow or deliberate tone mapping; changing only the pixel format can produce incorrect colours. In a graphical encoder, choose MP4, H.264, AAC and a web-optimised export, then verify the saved file instead of relying on its preset name.

5. Test a simple HTML video element

Temporarily remove the custom player from a test page and embed a minimal video element. Our introduction to the HTML video element covers the basic syntax. Its older browser notes reflect the article’s publication period.

<video controls playsinline preload="metadata" width="1280" height="720">
  <source src="/media/output-web.mp4" type="video/mp4">
  Your browser does not support HTML video.
</video>

Substitute the example path with your real file URL and use the video’s actual dimensions. Apply responsive CSS like max-width: 100%; height: auto;. Use visible controls and click Play manually. This test explicitly leaves out autoplay.

Offer alternative encodings by providing separate source elements with accurate MIME types. Guessing a codecs parameter can cause the browser to skip a source. Fallback text inside the video element applies to browsers without video support; it is not a reliable error message for modern browsers unable to display a file.

6. Replace the WordPress file and check the delivered copy

Upload the converted video as a separate media item and select it within the WordPress Video block or player settings. Acceptance of an upload by WordPress does not mean that all browsers will play the video successfully.

Choose a new filename when practical. Clear relevant page and CDN caches, then confirm that the player requests the new URL through Network. Test playback, sound and seeking across your audience’s browsers and devices, including a phone.

If a simple embed works but the plugin player fails, inspect the player’s configuration, scripts and streaming requirements. If playback works but processing frames fails, refer to our video and canvas tutorial for background on that separate task. Cross-origin canvas access requires its own checks.

Watch: how video encoding works

Google for Developers’ “Demystifying encodes and decodes of WebM” provides background on WebM encoding for web distribution. This archived 2014 talk explains encoding concepts; however, its browser and performance comparisons should not be considered current compatibility advice.

Frequently asked questions

Can I fix HTML5 video not properly encoded without converting it?

Yes, if the cause is an incorrect URL, blocked request, wrong response header or stale cache. Check delivery first. Re-encoding is appropriate when the file is damaged or its tracks and encoding settings are unsuitable.

Why does the MP4 work in VLC but fail on my website?

VLC may support a codec or profile that the browser does not. Local playback also bypasses your website’s HTTP delivery. Inspect both the file and the browser’s Network response.

Does muted autoplay fix an encoding error?

No. Muting can help with autoplay restrictions, subject to browser policy. It cannot supply a missing decoder or repair a broken video stream. Test with visible controls and a manual click first.

Join the discussion.

Some HTML is ok

You can use these tags:
<a href="" title="">
<abbr title="">
<b>
<blockquote cite="">
<cite>
<del datetime="">
<em>
<i>
<q cite="">
<strong>

You can also use <code>, and remember to use &lt; and &gt; for brackets.