URL rewriting
URL rewriting is how WP Media Cloud makes cloud-stored files appear seamlessly in your WordPress site. Rather than modifying every URL stored in your database, WP Media Cloud intercepts WordPress’s own attachment URL functions and rewrites the output at the point of delivery. This document explains how that works, what it covers, and what it does not.
How URL rewriting works#
WordPress has a set of core functions that any theme, plugin, or page builder calls to retrieve attachment URLs. The most common are wp_get_attachment_url(), wp_get_attachment_image_src(), and wp_get_attachment_image(). WP Media Cloud hooks into these functions and replaces the local server URL with the cloud storage URL before the result is returned.
This means the rewriting happens at output time, not at storage time. The attachment record in your database still contains the original local path. WP Media Cloud reads that path, constructs the equivalent cloud storage URL, and returns that instead. Nothing in your database is permanently modified by URL rewriting alone.
What gets rewritten#
URL rewriting applies to any URL generated through WordPress’s attachment functions. This covers:
- Featured images on posts, pages, and custom post types
- Images in the block editor and classic editor post content
- Gallery blocks and image gallery shortcodes
- Images output through page builders (Bricks, Elementor, Divi, and others)
- Custom field image and file values (ACF, Meta Box, JetEngine, Pods, and others)
- WooCommerce product images, gallery images, and category images
- BuddyBoss profile photos, cover images, group images, and activity media
- Responsive image srcset attributes
- All registered thumbnail sizes
What does not get rewritten#
URL rewriting only works for URLs generated dynamically through WordPress attachment functions. It does not cover:
- Hardcoded URLs in theme files — if your theme outputs an image URL directly as a string rather than through a WordPress function, WP Media Cloud cannot intercept it.
- URLs saved as plain text in post content — if a URL was typed or pasted directly into a post as a raw string rather than inserted as a WordPress attachment, it is not an attachment record and is not rewritten.
- URLs saved in post content during a page builder session — some page builders save the full URL string into post content or postmeta rather than storing only the attachment ID. If the URL was saved before WP Media Cloud was configured, it will contain the old local URL and will not be rewritten dynamically. Use the URL Replace tool to update these.
- Theme assets, plugin assets, and files outside wp-content/uploads — these are not attachment records and are not touched by WP Media Cloud.
CDN URL rewriting#
If you have configured a CDN in WP Media Cloud > Settings > CDN, the CDN hostname is used in place of the storage bucket hostname in all rewritten URLs. The file path within the bucket remains unchanged. Switching CDN configuration takes effect immediately for all new URL output without any database changes.
What happens when WP Media Cloud is deactivated#
Because URL rewriting happens at output time via hooks, deactivating WP Media Cloud immediately stops all rewriting. WordPress falls back to its default behaviour and generates local server URLs for all attachments.
If local file removal was enabled and local copies were deleted, those local URLs will return 404 errors. Your files are still safe in cloud storage, but WordPress no longer knows how to find them. Reactivating WP Media Cloud restores all URLs immediately.
If you need to permanently deactivate WP Media Cloud, run the URL Replace tool first to write cloud URLs directly into your database, and ensure local file removal is disabled so local copies remain available.
Fixing URLs that are not being rewritten#
If some images on your site are not loading after enabling WP Media Cloud, the most likely causes are:
- The file was not offloaded — check the bulk migration tool to confirm all files have been processed
- The URL was hardcoded or saved as a plain string — use the URL Replace tool to update these
- A caching plugin is serving a cached version of the page with old local URLs — clear your page cache after configuring WP Media Cloud
- A page builder saved the full URL into postmeta — use the URL Replace tool
See Troubleshooting: images not loading for a full diagnostic guide.