Diagnosing a CMS Media Plugin That Stops Delivering

Start outside the CMS

Before opening a single plugin setting, take the URL the page is trying to load — from the browser’s network panel or the rendered <img src> — and open it directly in a fresh tab, or fetch it with curl -I. This one step splits the problem in half.

If the URL serves the right asset with the right transformation, then storage, the transformation pipeline and the delivery network are all working. Nothing below the plugin is at fault, and everything that follows is about how the plugin builds, caches or injects that URL. If the URL does not serve, the plugin is probably innocent: it is only displaying an upload, storage or delivery failure that lives somewhere else.

Do this first because it costs nothing and rules out half the stack. Cloudinary’s WordPress plugin troubleshooting tips are the plugin-side checklist to work through once this test has pointed at the plugin; there is little point reading them while the underlying URL is still returning an error. The same test applies to any of the platforms in Cloudinary’s CMS integrations list — the plugin differs, the delivery URL does not. Where the media layer sits behind a headless CMS instead of a monolith, the URL is usually easier to get at, because the front end receives it as a field rather than as rendered HTML; the trade-offs of that arrangement are covered in media handling inside a headless CMS.

Symptom: images missing or broken on the page

Likely cause. One of three distinct failures — at upload, at storage, or at delivery — that produce an identical broken image in the page. They have different owners, and picking the wrong one is how a ticket bounces between the CMS team, the plugin vendor and the media platform for a week.

Check. For each broken asset, work down the chain and stop at the first failure:

1. Upload. Log into the media platform’s own console — not the CMS media library, the platform’s — and search for the asset. If it is not there, the upload never completed. Owner: the plugin and the CMS server it runs on (request size limits, timeouts, a sync job that stalled).
2. Storage. If it is there, is it the file you expect? Check the public ID or path, the folder, and whether it was renamed, moved or deleted and re-uploaded under a new identifier. Owner: whoever administers the media platform account, and any automation acting on it.
3. Delivery. If the asset is present and correct, take its delivery URL from the console and open it. If that fails, the problem is on the delivery side — the transformation string, access restrictions, a custom domain that is not resolving. Owner: the media platform, the CDN in front of it, and the browser cache.

Fix. Upload failures: re-trigger the plugin’s sync for the affected assets and check its own log for the reason the first attempt stopped. Storage failures: restore the asset under the identifier the CMS references, or update the reference in the CMS to the new one — and check whether a retention rule removed it, because automated asset expiry will happily delete something a published page still points at. Delivery failures: fix the URL or the delivery configuration on the platform side; there is nothing to change in the plugin.

Write down which of the three it was. That word — upload, storage or delivery — is the single most useful thing in a support ticket, and it is the one most tickets omit.

Symptom: a transformation change does not apply

Likely cause. The plugin is caching its own copy of the delivery URL. You changed a preset, a crop, a quality setting or a named transformation on the platform side; the platform now serves the new version at the new URL; but the plugin keeps injecting the URL it stored when the asset was first synced. In the page this reads as the change not applying, and the reflex is to go back and change it again.

Check. Compare two URLs: the one in the rendered HTML, and the one the media platform’s console shows for the same asset with the transformation you intended. If the HTML still carries the old transformation string, the plugin cached it. Confirm by opening the console’s URL directly in the browser — it serves the new version, which proves the platform side is done and only the stored URL is stale.

Fix. Clear the plugin’s own cache or re-sync the affected assets so it rebuilds the URL, then check whether a second layer — the CMS page cache or object cache — also stored the old HTML and needs purging. Do not purge the CDN: nothing on the delivery side is stale, and a CDN purge is the expensive fix for a problem that is not there. This is worth knowing before you run any sitewide rewrite, because standardising branding across media without editing each asset is exactly the kind of change that lands on the platform in seconds and then appears to do nothing for as long as the plugin holds the old URLs.

Symptom: the asset picker is empty

Likely cause. Expired, rotated or revoked credentials inside the plugin. This is the one that costs the most time, because credential expiry in a plugin surfaces as an empty library, not as an authentication error. Nobody reads an empty picker as an auth failure; they read it as the assets being gone.

Check. Log into the media platform directly and confirm the assets exist. If they do and the plugin shows none, treat it as an authentication problem until proven otherwise. Then compare what the plugin has stored — cloud name, API key, and for Cloudinary the product environment it points at — against what the console shows. Ask whether a key was rotated, a user was removed, or the plugin was configured against a product environment that has since been renamed or retired. As a side check, open one of the site’s already-published images: if it still serves, delivery is unaffected and you have confirmed the failure is confined to the plugin’s authenticated calls.

Fix. Re-enter or re-authorise the credentials in the plugin, save, and reload the picker. If it populates, you are done; if it stays empty with credentials you have just verified, you are past the auth layer and into the version problem below.

Symptom: configuration looks correct and it still fails

Likely cause. An unsupported plugin and platform version pair. Either version can be current on its own and the combination can still be broken — a plugin release built against one platform major, running on the next; or a platform update that changed a hook the plugin depended on. The pair matters more than either number, and the pair is what a support ticket needs.

Check. Record the exact plugin version and the exact platform version together, from the running system rather than from memory. Look up the plugin’s changelog or compatibility notes for that pair. If a staging environment exists, reproduce there with the same pair; if you cannot, the pair is still the first line of the ticket.

Fix. Move one side to a documented-compatible version — usually the plugin, since the platform is harder to roll back — and retest with the browser check from the top of this page. For platforms without a first-party plugin, where the integration is your own code following the guidance for integrating Cloudinary with other platforms, the same rule holds with the SDK standing in for the plugin: SDK version plus platform version is the pair to record.

What to send with the ticket

If you have worked down this page, you already have everything the ticket needs, in the order support will ask for it:

• The delivery URL, and whether it serves outside the CMS.
• Which stage failed: upload, storage or delivery.
• The URL the plugin rendered against the URL the platform expects, if they differ.
• Whether the picker populates with freshly verified credentials.
• The plugin version and platform version, as a pair.

A ticket with those five lines gets routed to the right owner on the first pass. One without them gets a request for exactly those five lines, a day later.