Troubleshooting
WordPress Videos Not Working: Causes and How to Fix It

Short answer
WordPress videos usually fail because the file uses a codec browsers cannot play, it exceeds the upload limit, the embed URL is wrong, or a caching plugin breaks the player. Re-encode to H.264 MP4, raise limits and test with optimization features paused.
Key takeaways
- MP4 with H.264 video and AAC audio plays in almost every browser.
- Phone videos in HEVC often upload but show a black box.
- Upload failures usually mean the file exceeds the server limit.
- Autoplay only works reliably when the video is muted.
- Script delay and minify settings can break video players.
Why are WordPress videos not working?
WordPress videos usually stop working because of an unsupported video format, an upload size limit, a broken embed link, or a plugin or caching conflict on the page.
The symptom tells you a lot. A video that will not upload points to server limits, while a video that uploads but shows a black box or spinning wheel usually points to the file's codec or to a script conflict.
Embedded videos from YouTube or Vimeo fail for different reasons than self-hosted files. Their problems tend to be about the link, privacy settings or a blocked script.
This guide covers both types. Start with the section that matches what you see, then work through the checklist near the end.
| Symptom | Most likely cause | Where to look |
|---|---|---|
| Upload fails or stalls | File too large or execution time too short | Server upload limits |
| Sorry, you are not allowed to upload this file type | Unsupported file extension | File format |
| Black box, sound but no picture | Unsupported codec such as HEVC | Re-encode to H.264 MP4 |
| Plays on desktop, not on iPhone | Codec or missing range support | Encoding and server |
| Embed shows a plain link | Bad URL or embed blocked | Embed block and plugins |
| Autoplay does not start | Browser autoplay rules | Mute the video |
| Player missing after a change | Caching or optimization plugin | Script delay and minify settings |
Is the video format supported?
The safest format for WordPress is an MP4 file using the H.264 video codec and AAC audio, because almost every browser can play it.
WordPress accepts several video file types, including MP4, MOV, WebM and OGV, and the get_allowed_mime_types() reference shows how that list is built. But accepting a file is not the same as the browser being able to play it.
The MDN guide to web video codecs explains why. The container, such as MP4 or MOV, is just a wrapper, and the codec inside decides whether a browser can decode it.
Phones often record in HEVC, also called H.265. Support for it varies by browser and device, so a phone video can upload fine and then show a black box for many visitors.
The fix is to re-encode the file to H.264 MP4. Free tools such as HandBrake can do this, and its standard web presets are a sensible starting point.
Is the video too large to upload?
If the upload fails, stalls or shows an error about file size, the video is almost certainly larger than your server's upload limit.
Hosting plans set a maximum upload size in PHP, and video files hit that limit far more often than images. You can see your current limit on the Media, Add New screen.
Our guide on fixing the upload_max_filesize error walks through the exact message.
For a broader look at raising the limit, see how to increase the max upload size in WordPress.
Large uploads can also run out of time before they finish. If the upload starts but never completes, the steps in how to increase max execution time may help.
Before raising limits, consider whether the file needs to be that big. Compressing a video to a sensible bitrate often cuts its size dramatically with little visible loss.
Why does the video upload but not play?
When a video uploads but will not play, the cause is usually the codec, a wrong MIME type from the server, or the server not supporting partial content requests.
Start with the codec. Open the file's details on your computer and check whether it uses H.264 or HEVC.
Next, open the video file's direct URL from the Media Library in a new tab. If it downloads instead of playing, or fails to load, the server may be sending the wrong content type.
Safari and iPhones are stricter than other browsers. They expect the server to support byte-range requests, which let the player load parts of the file. Most hosts support this, but some security or caching layers interfere with it, so ask your host if videos fail only on Apple devices.
Mixed content can also block playback. If your site uses HTTPS but the video URL starts with http, the browser may refuse to load it.
Why is an embedded YouTube or Vimeo video not showing?
Embedded videos usually fail because the URL is wrong, the video owner has disabled embedding, or a plugin is blocking the provider's scripts.
WordPress turns supported video links into players through oEmbed. The Embed block documentation explains how this works and which providers are supported.
Paste the plain watch URL, not a shortened or playlist URL with extra parameters. If the block shows only a link, try the provider-specific embed block instead.
Check the video's settings on the platform. Private videos, or videos with embedding turned off, will not play on your site.
Cookie consent and privacy plugins often block YouTube until a visitor accepts cookies. That is expected behaviour, but it can look like a fault when you test in a fresh browser.
Speed plugins can also delay or replace embeds with a preview image. Our guide on how to speed up YouTube embeds explains how those facades work.
Why won't the video autoplay?
Most browsers block autoplay with sound, so a video set to autoplay will only start on its own if it is also muted.
In the Video block settings, turn on Muted alongside Autoplay. Adding Plays inline helps on iPhones, where videos otherwise try to open full screen.
The WordPress Video block documentation lists the playback options available, including Loop, Controls and Preload.
If autoplay still fails, check whether a page builder or slider is overriding these settings with its own player.
Could a plugin, theme or cache be breaking the player?
Yes, optimization and caching plugins often break video players by delaying, combining or minifying the scripts the player depends on.
WordPress uses the MediaElement.js player for some video output, and page builders and themes may load their own players. If a speed plugin delays all JavaScript until user interaction, the player may never start.
Turn off script delay, minification and combining one at a time, clearing the cache after each change. If the video comes back, exclude the player's scripts in that setting instead of leaving the whole feature off.
If that does not help, run a conflict test. Switch to a default theme and disable plugins on a staging copy, then reactivate them one by one.
CDNs can cause trouble too. Some cache video files badly or strip range support, so test with the CDN paused if videos fail only on the live domain.
How do you fix WordPress videos step by step?
Work through the quick checks first, and test after each change so you know which one fixed it.
- Open the page in a private window and another browser.
- Check the file is MP4 with H.264 video and AAC audio.
- Re-encode HEVC or unusual files with a tool like HandBrake.
- Confirm the upload limit is larger than the file.
- Open the video's direct URL to see whether it loads.
- Make sure the URL uses HTTPS on an HTTPS site.
- For embeds, use the plain URL and check embedding is allowed.
- Pause caching, script delay and CDN features, then retest.
- Run a plugin and theme conflict test on staging.
Keep notes as you go. If you need to contact your host, being able to say the file plays from its direct URL but not in the player saves a lot of time.
Should you self-host videos or use YouTube?
For most sites, hosting videos on YouTube, Vimeo or a dedicated video service is more reliable than uploading them to WordPress.
Video services handle encoding, adaptive streaming and bandwidth for you. Shared hosting plans are not built to stream large files to many visitors at once.
Self-hosting gives you more control and no third-party branding, which suits short background clips and product loops. Keep those files small and well compressed.
Our comparison of self-hosting videos versus embedding YouTube covers the trade-offs in more detail.
When should you ask your host for help?
Contact your host when uploads fail even after raising limits, or when the direct video URL will not load or plays only in some browsers.
These signs point to server settings you may not control, such as MIME types, security rules or byte-range support.
Tell support the file name, its size, its codec, the browsers you tested and what you already tried. That lets them check the server logs instead of repeating your basic checks.
Frequently asked questions
What video format is best for WordPress?
MP4 using the H.264 video codec and AAC audio is the safest choice, because nearly every browser and device can play it. WebM is a good second option. Avoid uploading HEVC files straight from a phone without re-encoding them first.
Why does my WordPress video play on desktop but not on iPhone?
iPhones are stricter about codecs and expect the server to support byte-range requests. Re-encode the file to H.264 MP4 and turn on the Plays inline option. If it still fails, ask your host whether a security or caching layer is blocking range requests.
Why does my YouTube video show as a link in WordPress?
WordPress could not turn the URL into an embed. Check that you pasted a plain watch URL, that the video allows embedding, and that no privacy or speed plugin is blocking the provider. Trying the dedicated YouTube embed block can also help.
How do I upload a video larger than the WordPress limit?
Either raise the PHP upload limit through your host's control panel or settings, or compress the video so it fits. For long or high-resolution videos, hosting them on YouTube or Vimeo and embedding them is usually the better option.
Sources
- Video codecs used on the web MDN Web Docs
- Video block WordPress.org Documentation
- Embed block WordPress.org Documentation
- HandBrake HandBrake
- The Video Embed element MDN Web Docs
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


