Troubleshooting
WordPress Video Embed Not Working: Causes and How to Fix It

Short answer
A WordPress video embed usually breaks because the URL is not in a supported format, the owner turned off embedding, or a cache, consent or speed plugin blocks the player. Paste a clean link into an Embed block, check the video's privacy settings, then test with optimization features paused.
Key takeaways
- WordPress uses oEmbed to turn supported video links into players.
- Private videos and those with embedding disabled will never play on your site.
- Lazy loading and script delay settings often leave a blank box.
- Cookie consent tools can hide players until visitors accept cookies.
- Provider iframe code in a Custom HTML block is the fallback.
Why is a WordPress video embed not working?
A WordPress video embed usually fails because the URL is not one WordPress recognizes, the video owner blocked embedding, or a plugin, cache or privacy tool stops the player from loading.
Embeds work differently from uploaded videos. When you paste a YouTube or Vimeo link, WordPress asks that service for embed code through a system called oEmbed, then caches the answer.
If any step in that chain breaks, you see a plain link, an empty box, or a player that says the video is unavailable.
This guide focuses on embedded videos from services such as YouTube, Vimeo and TikTok. If your problem is with a video file you uploaded to the Media Library, our guide to WordPress videos not working covers codecs and upload limits.
| What you see | Likely cause | Where to fix it |
|---|---|---|
| Plain text link instead of a player | URL format not recognized, or embed fetch failed | Use the right block and a clean URL |
| This content cannot be embedded in the editor | Provider not supported or request blocked | Check provider list and server |
| Video unavailable inside the player | Owner disabled embedding or set the video private | Video settings on the platform |
| Player works for you, not for visitors | Cookie consent or privacy plugin blocking it | Consent and privacy settings |
| Blank space after enabling speed plugin | Lazy loading or script delay conflict | Cache and optimization settings |
| Works in editor, not on live page | Stale page cache or CDN cache | Clear all caches |
Is the video URL in the right format?
WordPress only turns a link into a player when the URL matches a supported provider pattern, so a shortened, tracking-heavy or private link often stays as plain text.
Copy the link from the video page's address bar or its Share button. For YouTube, both the youtube.com/watch link and the youtu.be short link work.
Remove extra parameters after the video ID if the embed fails. Links copied from playlists, search results or apps often carry tracking data that can confuse the match.
Paste the URL on its own line in the classic editor. In the block editor, use the YouTube, Vimeo or generic Embed block and paste the link into its field.
The WordPress embeds documentation lists the providers that work out of the box. Services not on that list need a plugin or their own iframe code.
Has the video owner blocked embedding?
If the player loads but shows Video unavailable or a similar message, the video owner has probably turned off embedding or made the video private.
On YouTube, creators can switch off Allow embedding in the video's advanced settings. Some music and sports videos also block playback on other sites for copyright reasons.
Private videos never play in embeds. Unlisted videos usually do, because anyone with the link can watch them.
Vimeo gives owners even more control. Its privacy settings can limit embeds to specific domains, so a video may play on one site and fail on yours. Vimeo's help center explains these privacy options in detail.
If the video is yours, check those settings first. If it belongs to someone else, you cannot change them, so choose another video or link to it instead.
Could WordPress fail to fetch the embed?
Yes, WordPress needs to contact the video service from your server, and a firewall, DNS problem or blocked outbound request can stop that.
When you paste a link, your server sends a request to the provider's oEmbed endpoint. If your host blocks outgoing connections or the request times out, the editor shows an error and the front end keeps a plain link.
Test this by pasting a well-known public YouTube video into a new draft. If that also fails, the problem is on the server side rather than with your video.
Security plugins and hosts sometimes block outbound requests through the WP_HTTP_BLOCK_EXTERNAL constant in wp-config.php. If it is set to true, WordPress cannot reach providers unless they are allowed in WP_ACCESSIBLE_HOSTS.
The Site Health tool under Tools can also reveal problems with outbound requests and the REST API, both of which the embed preview relies on. Our guide to fixing REST API errors in Site Health helps if that check fails.
Is a cache or speed plugin hiding the player?
Speed plugins often replace video iframes with placeholders or delay their scripts, and a misconfigured setting can leave an empty box instead of a player.
Common settings to test are lazy loading for iframes and videos, replace YouTube iframe with preview image, delay JavaScript execution and combined or minified scripts.
Turn these features off one at a time, clear the cache, and reload the page in a private window. When the player returns, you have found the setting to adjust or exclude.
Lazy loading videos is still a good idea for speed. Our guide on speeding up YouTube embeds shows how to keep the benefit without breaking playback.
Remember to clear every cache layer. That includes your plugin cache, server cache and any CDN, as explained in our guide to clearing cache in WordPress.
Are privacy or consent tools blocking the video?
Cookie consent plugins often block YouTube and Vimeo players until a visitor accepts marketing or third-party cookies, so the video looks broken to new visitors.
This is expected behavior for many consent setups. Logged-in admins may have already accepted cookies, so the problem only appears for visitors or in a private window.
Look at the consent banner settings. Most tools show a placeholder with a button to load the video, and you can change the message so visitors understand why the player is hidden.
YouTube also offers a privacy-enhanced mode that uses the youtube-nocookie.com domain, described in the YouTube embed help page. Some site owners use it to reduce tracking, though it does not replace a proper consent setup where the law requires one. This is general information, not legal advice.
Could the theme or another plugin break the embed?
Yes, a theme or plugin can remove oEmbed support, filter iframes out of content, or load CSS that collapses the player to zero height.
Switch to a default theme such as Twenty Twenty-Five on a staging site and test the page. If the video appears, your theme is the cause.
Next, deactivate plugins one by one. Page builders, security plugins, AMP plugins and content filters are the usual suspects.
Some security setups strip iframe tags for users without the unfiltered_html capability. That matters if editors paste raw iframe code. The capabilities reference explains which roles have this permission.
How do you refresh a stuck embed?
Edit the post, remove the embed, save, then paste the URL again in a fresh Embed block so WordPress fetches new embed code.
WordPress stores oEmbed results as post meta with keys that start with _oembed_. If the first fetch failed, the failure can be cached, and the link keeps showing as plain text.
Re-saving the post usually clears this. For stubborn cases, a database cleanup plugin or WP-CLI can delete the cached oEmbed entries for that post.
You can also preview the embed in a new draft. If it works there but not in the original post, the cached data in the original is the likely problem.
What if the embed still will not work?
As a last resort, paste the provider's own iframe code into a Custom HTML block, which skips WordPress's oEmbed lookup completely.
On YouTube, click Share, then Embed, and copy the code. On Vimeo, use the embed option in the share menu.
Paste it into a Custom HTML block and preview the page. The MDN iframe reference explains the attributes in that code, such as allow and allowfullscreen. If the player appears, the problem was in the oEmbed step rather than the video.
Keep in mind that only users with permission to post unfiltered HTML can save iframe code. On multisite, that usually means Super Admins only.
If you host many videos, compare your options in our guide to self-hosting video versus embedding YouTube. Embeds save server resources, while self-hosting gives you more control.
What is the quickest checklist?
Work through these checks in order, testing the page in a private window after each one.
- Copy a clean video URL from the address bar or share button.
- Paste it into the matching Embed block.
- Confirm the video is public and allows embedding.
- Test a different public video to rule out server problems.
- Turn off lazy loading and script delay for iframes.
- Clear plugin, server and CDN caches.
- Check cookie consent settings in a private window.
- Switch theme and deactivate plugins on staging.
- Use the provider's iframe code in a Custom HTML block.
Most embeds start working again by step 5. If none of these help, your host can check whether outbound requests to the video service are being blocked.
Frequently asked questions
Why does my YouTube link show as text in WordPress?
WordPress could not match the link to a supported provider or failed to fetch the embed code. Paste a clean watch or short link into the YouTube or Embed block, remove extra tracking parameters, and save the post again so WordPress tries a fresh fetch.
Why does the video say unavailable on my site but plays on YouTube?
The owner has probably turned off embedding or restricted where the video can play. Copyright claims can also block playback on other sites. If it is your video, check the embedding setting in YouTube Studio.
Can a caching plugin break video embeds?
Yes. Lazy loading, iframe preview images, delayed JavaScript and combined scripts can stop the player from loading. Turn these features off one at a time, clear all caches and test in a private window to find the cause.
Why can visitors not see the video when I can?
A cookie consent tool may block third-party players until visitors accept cookies, while you already accepted them. A page cache or CDN may also serve an older version. Test in a private window to see what visitors see.
How do I embed a video from a site WordPress does not support?
Copy the iframe embed code from that service and paste it into a Custom HTML block. Your user account needs permission to post unfiltered HTML, which Administrators have on single sites.
Sources
- Embeds WordPress.org Documentation
- Site Health screen WordPress.org Documentation
- Roles and capabilities WordPress Developer Resources
- Embed videos and playlists YouTube Help
- The Inline Frame 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.


