WordPress oEmbed Not Working: How to Find the Cause and Fix It

This article is a localized edition of the Japanese original. Read the Japanese original

In WordPress, you can paste a URL from a service such as YouTube and the video or post appears inside the article. This mechanism is called oEmbed. When the URL stays a plain URL or link instead of turning into an embed, checking these points in order narrows down the cause.

1. How the URL was pasted, and whether WordPress supports the service
2. Whether an earlier failure has been saved (cached)
3. Whether the server can connect to the outside service
4. Whether the REST API used by the block editor is working
5. Whether a plugin or theme is blocking embeds

The behavior described here was checked against the WordPress 7.1 source code (wp-includes/class-wp-embed.php, class-wp-oembed.php) and tested with WP-CLI (as of October 2026).

How oEmbed works

A URL becomes an embed in these steps:

1. WordPress checks which registered service (provider) the URL belongs to
2. The server asks that service's oEmbed endpoint for the embed HTML
3. WordPress saves the HTML in the post's custom fields (metadata whose keys start with _oembed_) and shows the saved copy from then on

The request is made by the server running WordPress, not by the visitor's browser. If the server's outbound connections are blocked, nothing can be embedded. Failed results are saved as well, so the URL can stay a link even after you fix the cause.

1. Check how the URL is pasted and whether the service is supported

Paste the URL alone on its own line

• Block editor: paste only the URL into an empty paragraph and it turns into an embed block. If you paste it in the middle of text, it becomes a normal link. You can also add an "Embed" block or a "YouTube" block and enter the URL there.
• Classic Editor: put the URL on a line of its own with nothing before or after it. If the URL has a link (an a tag) on it, it will not be embedded.

Is the service supported?

The services WordPress supports out of the box are registered in class-wp-oembed.php. If you can use WP-CLI, this command tells you whether a URL is supported.

# If the URL is supported, the provider's endpoint URL is shown
wp embed provider match https://www.youtube.com/watch?v=jNQXAC9IVRw

For an unsupported URL you get Error: No oEmbed provider found for given URL. These are the services that most often cause trouble:

For an X post, replace x.com in the URL with twitter.com and paste it; it will then be embedded (for example https://x.com/username/status/ID → https://twitter.com/username/status/ID). For Instagram embeds, see Instagram embeds not showing in WordPress.

2. Clear the saved failure (cache)

Once an embed fails, WordPress saves the failure in the post's metadata (the value is {{unknown}}) and keeps showing that URL as a link. Even after you fix a connection problem, the display does not change until this record is deleted. On WordPress 7.1 we confirmed that if a page is shown once while outbound connections are blocked, so the failure is saved, the URL stays a link after the connection is restored, and becomes an embed again once the cache is cleared.

Clearing it with WP-CLI

# Delete all oEmbed caches stored for post ID 123
wp embed cache clear 123

The next time the article is viewed, WordPress asks the service again.

Embeds outside posts, such as in widgets, are stored in a post type called oembed_cache. Find the ID with the first command below and delete it.

# Find the ID that holds the cache for the URL
wp embed cache find https://www.youtube.com/watch?v=jNQXAC9IVRw

# Delete the ID that was shown (example: 456)
wp post delete 456 --force

Clearing it with phpMyAdmin or similar

If you cannot use WP-CLI, delete the metadata in the database. Back up the database before you run this. Change the wp_ in the table name to your site's prefix.

-- Delete the oEmbed cache of post ID 123 (meta keys starting with _oembed_ and _oembed_time_)
DELETE FROM wp_postmeta
WHERE post_id = 123
  AND meta_key LIKE '\_oembed\_%';

3. Check whether the server can connect to the outside

If embeds still fail after clearing the cache, check whether the server can reach the service. WP-CLI's wp embed fetch makes the request the same way WordPress does.

# If the embed HTML is printed, the request succeeded
wp embed fetch https://www.youtube.com/watch?v=jNQXAC9IVRw

If you get Error: There was an error fetching the oEmbed data., check directly with WordPress's HTTP functions whether the connection itself fails.

# 200 means the connection works. On failure, the reason is printed
wp eval '$r = wp_remote_get( "https://www.youtube.com/oembed?format=json&url=https://www.youtube.com/watch?v=jNQXAC9IVRw" ); echo is_wp_error( $r ) ? $r->get_error_message() : wp_remote_retrieve_response_code( $r );'

Possible causes when the server cannot connect:

• Outbound requests are blocked in wp-config.php: with define( 'WP_HTTP_BLOCK_EXTERNAL', true );, every outbound HTTP request is stopped. To use embeds, list the allowed host names, separated by commas, in WP_ACCESSIBLE_HOSTS, or remove this setting.
• The server or hosting company restricts outbound traffic: check your host's documentation or support to see whether the server's firewall blocks outbound connections.
• DNS or SSL certificate verification fails: use the error message printed by the command above (cURL error 6, cURL error 60 and so on) as a clue.

Note that WordPress's server-side requests go through the HTTP API (cURL and similar), so PHP's allow_url_fopen setting has nothing to do with oEmbed.

4. When the block editor says “Sorry, this content could not be embedded.”

When you enter a URL in the block editor, you may see "Sorry, this content could not be embedded." with the buttons "Try again" and "Convert to link". The editor fetches the preview through the WordPress REST API (/wp-json/oembed/1.0/proxy). Check the following:

• Whether wp embed fetch from the previous section succeeds. If it fails, the cause is the server's connection or the service itself
• Whether the REST API works. If a security plugin or .htaccess blocks access to /wp-json/, embedding in the editor fails too. See What to do when the WordPress REST API does not work for how to check
• Whether the video or post is private or deleted, or the video does not allow embedding. In that case it cannot be fixed on the WordPress side

5. Check plugins, the theme and the browser

• Plugins or settings that block embeds: some performance and security plugins have a setting that disables the embed feature. Deactivate all plugins temporarily and switch to a default theme (such as Twenty Twenty-Five) to see whether embeds come back; this narrows down the cause. Do this on a test environment rather than the production site.
• An X post shows only as text: an X embed first appears as a quote (blockquote) and changes into the post layout once X's script loads. If a browser ad blocker, the site's Content Security Policy (CSP) or a cookie consent plugin blocks that script, you only see the text.
• The iframe does not appear: check the console in the browser's developer tools for errors. If the embed's host is not allowed in the CSP frame-src, the iframe does not load.

Keep an error log to investigate

If you still cannot find the cause, enable the debug log in wp-config.php, view the article, and then check wp-content/debug.log. The setup is explained in How to enable WordPress debug mode in wp-config.php.

Summary

• Paste the URL on a line of its own, without a link. Check whether it is supported with wp embed provider match
• Paste X posts as twitter.com URLs. Since WordPress 5.5.2, Instagram and Facebook cannot be embedded out of the box
• Failures are saved in the post's metadata, so after fixing the cause, clear the cache with wp embed cache clear POST_ID
• The server fetches the embed HTML. Check its outbound connections with wp embed fetch and wp_remote_get()
• For errors in the block editor, also check the state of the REST API

Related articles

• WordPress embeds (oEmbed) not showing: causes and fixes for YouTube, X and Instagram
• How to embed videos in WordPress posts (YouTube, Vimeo, video files, built-in features)
• What to do when the WordPress REST API does not work: 404, 401, 403 and rest_no_route

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)