Clearing the WordPress oEmbed Cache

May 31, 2019

WordPress has great support for embedding content from other services just by using a URL. For example, if you paste a YouTube URL into the editor, when WordPress displays the post it will render an embedded YouTube player on your site.

However, sometimes oEmbeds don’t load and you’re left with the text of the URL instead. This can happen for a few reasons but generally it can be fixed.

I noticed this the other day on the WP App Store site, which features two Tweets as testimonials from subscribers of the site, side by side. One wasn’t loading, making it look a little broken:

How oEmbeds Work

When you enter an external URL into the WordPress content editor WordPress checks with the third-party site if there is any content to be returned and embedded.

WordPress caches the returned content so it doesn’t need to do the request to the URL again, and stores this in the postmeta table against the post ID of the post/page the URL is used in. The cache of the content expires after a certain time and the next time the post is loaded a fresh request is made.

{{unknown}} cache

After inspecting the site’s postmeta table for the post ID of the homepage I found the two entries of _oembed_ to store the content and cache timeout timestamp. One cache entry looked correct with <blockquote> HTML with the tweet, but the other simply had {{unknown}} as the meta_value:

David Law has a comprehensive post explaining how to understand and resolve these types of broken cache entries, but I didn’t want to be diving into the database every time this happened to manually delete the entry.

Clearing the Cache

I would assume WordPress would clear the cache of broken embeds on a cron job and try to refresh them successfully but I have seen broken embeds stick around for quite sometime before fixing them, so I assume not. I plan to investigate when I have some time.

In the short term, the quick fix I found was to use the awesome WP CLI to clear the cache using the command wp embed cache clear 17 where 17 is the post ID of my homepage.

This isn’t completely ideal as it clears the cache of successfully fetched embed content but as the data is transient anyway, it’s a case of clearing it sooner rather than later.

It would be a good addition to the command to be able to run wp embed cache clear --broken to search for whole cache and only clear broken entries.

Have you come across the broken {{unknown}} cache entries for oEmbeds before? If you’ve found a better fix then please let me know in the comments.

About Iain

I am a WordPress and PHP developer building my own plugins and working with Delicious Brains. I like to blog about things, especially WordPress.