WP Offload Media - WordPress Plugin

Guide to Configuring and Safely Using WP Offload Media

WP Offload Media is not meant to dress up the WordPress admin area. It solves a specific infrastructure problem: moving files from the WordPress Media Library into object storage, rewriting links to remote URLs, and, when needed, serving images, documents, video files, CSS, JavaScript, and fonts through a CDN. This guide covers more than installation. It explains the configuration logic behind the plugin: which provider to choose, when to enable local file removal, how to validate URLs, where permission issues usually appear, why background tasks depend on cron, and how to avoid breaking your Media Library on a live site.

This article is written for site owners, WordPress administrators, and developers who need to understand how to use WP Offload Media in a real project. It does not cover purchasing the plugin, activating a commercial license, or bypassing product limitations. The focus is strictly on practical use of an existing installation: preparation, storage setup, delivery configuration, migrating an existing Media Library, verifying the result, troubleshooting, and comparing similar solutions.

It is important to start with the right mental model: the plugin does not magically make WordPress fast on its own. It reduces the load tied to file storage, helps move media into S3-compatible or cloud storage, rewrites URLs, and adds tools to manage offload status. Speed, security, and reliability still depend on how the bucket, CDN, permissions, site cache, backups, and theme or plugin compatibility are configured.

That is why this guide is structured from the initial task to result verification. First, we will define who the product is a good fit for. Then we will walk through preparation, storage and delivery settings, a practical media migration workflow, troubleshooting, and common questions. This order is safer than flipping every switch first and then trying to figure out why images disappeared from product cards, editor blocks, or older posts.

What Problem the Plugin Solves and Where It Is Most Useful

The main purpose of WP Offload Media is to separate media storage and delivery from the local WordPress filesystem. When a user uploads a file through the standard media uploader, WordPress still receives it on the server, generates the required image sizes, and saves the record in its internal Media Library. After that, the plugin copies the file and its derived sizes to the selected storage provider and replaces local URLs on the site with remote URLs from the provider or CDN.

This setup is especially useful for sites with large media libraries, stores with heavy product images, online magazines, catalogs, learning platforms, membership sites, and projects that run across multiple servers. If files live only on a single web server, migrations, load balancing, and scaling become harder: you have to sync the wp-content/uploads folder, watch disk space, and remember that a site backup can suddenly turn into a massive archive. Offloading changes that model: WordPress keeps the metadata, while the physical objects live in the cloud.

The plugin is most valuable when the bottleneck is tied to media storage, delivery, and management. If the site is slow because of a bloated theme, inefficient queries, missing page cache, an overloaded page builder, or weak hosting, moving files to the cloud will not solve everything by itself. But it can remove part of the load from the origin server, make the Media Library portable, simplify backups, and provide a clean path to CDN delivery with a custom domain such as media.example.com.

Typical Use Cases

In practice, WP Offload Media is usually introduced in a few common situations. First, the site has grown and the local disk is filling up faster than expected. Second, images and documents need to be served through a CDN so the origin server can focus on pages rather than every single file. Third, the project is moving to a cluster or autoscaling setup where the local uploads folder should no longer be the only source of truth. Fourth, digital products, private documents, or member-only materials need to be stored in a bucket and delivered through temporary signed URLs.

For a small blog with a few hundred images and standard caching, the benefit may be moderate. For a media project with thousands of images, a WooCommerce store with digital downloads, an editorial portal, or a site with multiple environments, the value is much more noticeable. That is especially true if you set up a CDN, a dedicated media subdomain, and a clear rollback plan from the start.

Who This Product May Not Be Right For

The plugin should not be installed "just in case" if you do not have access to storage settings, DNS, cron, and basic diagnostics. It adds an external dependency: the site now depends not only on WordPress hosting, but also on a cloud provider, a CDN, access keys, and bucket rules. If your team is not prepared to maintain that infrastructure, it is better to start with standard caching, image optimization, and good Media Library hygiene.

WP Offload Media is also not a replacement for real image optimization. It can work alongside optimization plugins and officially supports a range of integrations, but simply storing files in the cloud does not reduce the weight of JPEG, PNG, or WebP files. If images are not compressed, include unnecessary sizes, or are inserted without responsive attributes, the CDN will simply deliver an unoptimized file faster. The right stack looks like this: image optimization, stable page cache, media offload, CDN, and browser-level verification of the result.

What to Check Before Installation and First Launch

Preparation matters more with WP Offload Media than with a standard visual plugin. A mistake in permissions or domain setup can lead to broken images, stalled background jobs, or a situation where local files are deleted but remote URLs do not work for visitors. Before installation, it is worth doing a short audit.

Permissions, Backups, and a Test Environment

Start by making sure you have a fresh backup of both the database and the files. Even if you plan to keep local copies, offloading changes attachment metadata and URLs, and background tools are involved when working with an existing Media Library. On a live site, the safer approach is to start on a copy or staging environment, where you can connect a separate bucket, test URL rewriting, and see how the plugin behaves with your theme, editor blocks, galleries, and products.

The second item is access to the cloud provider. For Amazon S3, that usually means an IAM user or role with permissions to work with the bucket and its objects. For DigitalOcean Spaces, you need an access key and secret key. For Google Cloud Storage, you typically use a service account key file or another supported authentication method. Do not store real secrets in notes, tickets, the article, a public repository, or chat. In the project itself, use a secure location on the server or constants in wp-config.php if that matches your support policy.

Provider, Region, and Domain Name

It is best to choose the storage provider before installation. WP Offload Media supports Amazon S3, DigitalOcean Spaces, Google Cloud Storage, and some S3-compatible options through separate setup instructions. If you already use AWS, starting with S3 and CloudFront is the most logical path. If your infrastructure is simpler and your team is more comfortable with DigitalOcean, Spaces may be easier to manage. If the project already runs in Google Cloud, GCS is usually the easiest fit for existing workflows.

Choose the region based on your audience, data storage requirements, and CDN availability. For public images, CDN delivery usually matters more than the bucket region alone. For private materials, documents, and digital products, the more important factors are the access policy, signed URL lifetime, and a clear file recovery process.

Decide in advance whether you want to use a custom subdomain. For SEO, trust, and cleaner URLs, it is usually better to serve media from your own domain, such as media.example.com or cdn.example.com, rather than from a long raw bucket URL. But that approach requires DNS, an SSL certificate, and correct CDN configuration. If time is limited, you can test the basic offload flow first and add the custom domain as a separate step later.

Cron and Background Processes

Migrating an existing Media Library, changing object permissions, moving paths, and downloading files back to the server all rely on background jobs. WP Offload Media depends heavily on WordPress cron or a system cron working correctly. On sites with full page cache, Basic Auth, restricted staging access, or very low traffic, the default wp-cron.php can run inconsistently. The usual symptom looks like this: the offload tool shows progress, but barely moves, jobs stall, and some files remain in an in-between state.

Practical check: before migrating the full Media Library, upload one new file, confirm that it appears in the bucket, and then verify that WordPress background events are running regularly. Only start the large migration after that check passes.

Installation and a Safe First Launch

Installing the plugin is technically simple: add it through the WordPress admin area, activate it, and open its settings page through Settings -> Offload Media. The real complexity starts after activation, because now you need to connect WordPress to external storage without enabling risky options too early.

The First Settings Screen

If access credentials are not configured yet, the plugin shows a storage provider selection screen and a connection form. The official quick start guides walk you through separate setup flows for Amazon S3, DigitalOcean Spaces, and Google Cloud Storage. The logic is similar in all cases: create or select credentials, give them enough permissions for the bucket, save the authentication method, and then either choose an existing bucket or create a new one from the plugin interface.

For a first launch on a live site, the safer approach is "new uploads first, existing Media Library later." Enable offloading for new files, upload one test image, check the URL, and only then move on to older attachments. That order reduces risk: if something is wrong with permissions or the domain, the issue shows up on a single test file instead of the entire Media Library.

Create a New Bucket or Use an Existing One

If the project is new, it is usually easier to create a separate bucket for that specific site. That makes it easier to control the path, permissions, backup rules, lifecycle policy, and future migrations. If a bucket already exists, check whether another site is using it without a prefix. A single bucket can store files for multiple sites, but in that case you need a clear prefix so objects do not get mixed together.

For Amazon S3, pay special attention to Block All Public Access and Object Ownership. These settings affect whether the site can serve files directly, through a third-party CDN, or through CloudFront. If you are using CloudFront as the delivery provider and the bucket is properly locked down with policies, strict security settings may be part of the correct architecture. But if you are serving raw S3 URLs or using a CDN that needs direct access to objects, an overly locked-down bucket will cause access errors.

Do not try to "fix" the issue by making the entire bucket public. For public media, a correct delivery policy and provider configuration are usually enough. Private files require a different setup, using signed URLs and a clear understanding of which objects should only be available temporarily. A secure bucket configuration is not the most open one. It is the one that matches your chosen delivery model.

Post-Activation Check

After saving the basic settings, upload a small test file through the standard WordPress Media Library. Open the attachment details and check whether a remote URL or bucket location appears. Then insert the image into a draft page and open the public side of the site in a private browser window. The image URL should point to the selected storage provider or delivery provider. If a CDN and custom domain are enabled, make sure it uses that exact domain.

At this stage, do not enable local file removal until you have tested your theme, editor, galleries, image optimization plugin, and product pages. As long as the local copy stays on the server, rollback is much easier: you can disable URL rewriting and the site will return to local files. Once local copies are removed, rollback requires downloading the files back from the bucket or restoring them from a backup.

The Key Settings That Determine the Outcome

Once the base connection is in place, the most important part begins: configuring your storage and delivery logic. WP Offload Media includes several toggles that may look similar at first glance, but they control different layers of the system: file copying, local file removal, bucket path structure, object versioning, URL rewriting, CDN domain mapping, HTTPS, and private delivery.

Offload Media

Offload Media controls automatic copying of new files from the Media Library to the bucket. In most cases, this setting is enabled by default after configuration. It is important to understand its boundary: it does not migrate older attachments that were uploaded before setup. For an existing Media Library, you need a separate Offload Tool, and its availability depends on the product version.

If you turn this setting off, new files will stop being sent to storage automatically, but objects that have already been offloaded will not disappear. When you turn it back on, the plugin may offer to process files that have not been moved yet. Use this toggle as a safe brake if you notice problems with new uploads, but not as a full rollback mechanism.

Remove Local Media

Remove Local Media deletes local copies after a successful offload. This is a powerful setting. It helps save disk space, but it also raises the compatibility bar. Some image-processing plugins, galleries, importers, editors, and custom code expect the physical file to exist in wp-content/uploads. If the file is gone, they may throw errors, skip processing, or generate broken thumbnails.

For a typical site, the safest order is this: keep local files first, verify that the theme and editor work correctly, and enable local file removal only after testing. If the site is business-critical, enable the setting on staging first, build a test page with an image, gallery, cover block, WooCommerce product, and any nonstandard fields, and then verify editing, image replacement, optimization, and frontend behavior.

Rollback rule: if enabling Remove Local Media causes broken images in the editor, optimizer, gallery, or product page, first turn local file removal off and use the tool that downloads files back to the server. Do not rush to delete the bucket or change the delivery domain.

Prefix, Year-Based Folders, and Object Versioning

Add Prefix to Bucket Path helps separate files inside a bucket. If one bucket serves multiple environments or sites, a prefix like site-a/ or production/ reduces the risk of mixing objects together. But once you have already performed a large offload, changing the prefix requires caution: the plugin may offer to move existing objects and update records, which is a background operation.

Add Year & Month to Bucket Path preserves the familiar monthly folder structure, similar to the standard WordPress uploads layout. That makes navigation easier and aligns with what many teams expect. Add Object Version to Bucket Path adds a unique path segment and helps with cache busting, especially when a CDN is involved. If a file is replaced or regenerated, the new version gets a new path, making it less likely that browsers and the CDN will keep serving the old object.

Delivery Provider, Custom Domain, and Force HTTPS

The storage provider controls where the file is stored. The delivery provider controls where the visitor retrieves it from. At first, offloaded media may be served through raw bucket URLs. That works, but it is not always the best approach: the URL looks technical, it may not be on your own domain, and it does not automatically provide CDN advantages. That is why the official documentation recommends using a CDN, such as Amazon CloudFront for S3, or another supported delivery provider.

Use Custom Domain Name (CNAME) lets you replace the provider's technical domain with your own subdomain. This is useful for cleaner URLs, stronger trust, HTTPS control, and long-term portability. But a CNAME requires a DNS record, a certificate, and correct CDN configuration. In the plugin field itself, enter the domain name without the https:// scheme if that is the format expected by that setting.

Force HTTPS is used to prevent media from being served over insecure URLs on an HTTPS site. For modern sites, the goal should be HTTPS delivery for all content. If enabling it causes mixed-content errors or files stop opening, check the CDN certificate, DNS, and the underlying delivery domain, not just the WordPress settings.

URL Preview as a Quick Check Before Saving

At the bottom of the settings page, the plugin shows a URL structure preview. It does not replace real browser testing, but it helps you see what will happen when you change the provider, prefix, custom domain, or object version. Use it before saving any questionable changes: if the preview unexpectedly shows a raw bucket URL instead of your CDN domain, or changes the path in a way you did not expect, stop and review the settings first.

Migrating an Existing Media Library and Using Background Tools

New uploads are only part of the job. On an established site, the bulk of the media usually already lives in the existing Media Library. This requires a careful plan, because the migration can affect thousands of attachments, multiple sizes for each image, documents, videos, products, and posts where those links are already embedded in the content.

How Bulk Offloading Works

The tool for migrating an existing Media Library goes through attachments, copies files that have not yet been offloaded into the bucket, and updates their location data. The operation runs in small batches rather than as one long request. That is the right approach for stability, but it depends on cron working correctly and on reasonable server limits.

Before starting a bulk migration, check three things. First, the bucket has enough space and the credentials have permission to create, read, and modify objects. Second, the server can reach its own admin-ajax.php or cron endpoint if background processing relies on it. Third, the site is not behind Basic Auth or a security plugin that blocks internal HTTP requests unless special headers are present.

Pause, Resume, and Progress Monitoring

If the tool shows progress, you do not necessarily have to keep the browser tab open. But for the first migration, it is a good idea to check the status periodically: how many files have been processed, whether errors are appearing, and whether the percentage has stopped moving. If the migration stalls, do not click the same button over and over. First check cron, logs, storage provider availability, and PHP limits.

On large sites, the migration can temporarily increase CPU, database, and network load. Schedule it during a low-traffic window. If your hosting environment limits background execution, migrate the Media Library in smaller chunks or discuss the limits with support. The goal is not to finish the migration at any cost. The goal is to avoid degrading the site for real visitors.

Downloading Files Back and Switching Providers

WP Offload Media also supports the reverse path: if local files have been removed, they can be downloaded back from the bucket to the server. This matters most before disabling the plugin, moving to another solution, or changing the site architecture. Do not deactivate the plugin on a site that is already serving remote-only files until you have confirmed that local copies have actually been restored.

Switching the storage provider is a separate project. You need to download or move existing offloaded files, update the provider settings, verify the paths, and run the offload flow again. If you already have a large amount of data in S3, do not switch to DigitalOcean Spaces or Google Cloud Storage in a single evening without a test environment. Check on a site copy how the plugin updates metadata and what happens to URLs in older posts.

CDN, Custom Domain, and Private Files

Even without a CDN, WP Offload Media can reduce disk usage and simplify infrastructure, but the biggest benefit usually comes from correct delivery. A CDN places files closer to visitors, reduces origin load, and lets you use a custom media domain. At the same time, a CDN is not just a checkbox inside WordPress. You need to configure the origin, DNS, the certificate, and verify that the plugin is rewriting URLs to the right destination.

Why Raw Bucket URLs Should Usually Be Replaced

A raw bucket URL such as bucket-name.s3.amazonaws.com works technically, but it looks like a third-party service and is not always ideal for delivery. On a public site, a subdomain on your own domain connected to a CDN is usually a better option. Then the page HTML points images to a clean URL, while the CDN pulls the original from the bucket and caches it at edge locations.

In the Amazon S3 plus CloudFront scenario, the flow is straightforward: create a distribution with the bucket as the origin, wait for it to finish deploying, choose Amazon CloudFront as the delivery provider, enter the distribution domain or your own CNAME, save the settings, and then test a file in the Media Library and on a public page. After that, you can separately lock down direct public access to the bucket if delivery runs through CloudFront and your policies support that design.

Private Media and Digital Files

For normal images inside posts, access should be public. For digital products, WooCommerce downloads, Easy Digital Downloads files, membership documents, or materials for a protected course, you need a different model. WP Offload Media can mark an offloaded media item as private and issue signed URLs. Those links are valid only for a limited time, which makes them harder to reuse outside the intended workflow.

This is where the relationship between the storage provider and the delivery provider becomes especially important. In S3-based private file setups, CloudFront with signed URLs and a separate private path is often the preferred option. What you should avoid is mixing "everything is public" with "some files are private" without a clear model. If the site contains both public images and restricted downloads, decide in advance which file types should be private, who changes their status, and how access is verified after purchase, account login, or opening a member-only page.

When CloudFront Is Not Required

CloudFront is not the only CDN option. The product documentation mentions support for other CDNs and includes separate instructions for several alternatives. But if you are working with S3, private files, and strict bucket access rules, CloudFront is usually easier to align with AWS policies. If you choose a different CDN, check how it accesses the origin, whether objects need to be publicly readable, whether it supports private delivery, and how HTTPS works on the custom domain.

Practical Scenario: Migrating a Site Media Library with a Large Catalog

Imagine a WordPress site with a large content catalog: articles, product pages, galleries, PDF guides, and images that already take up a significant amount of disk space. The goal is to connect WP Offload Media so that new files go into the bucket, older files are migrated gradually, public images are served through a CDN domain, and local copies are removed only after compatibility has been verified.

Goal

The target is a manageable setup: editors keep uploading images through the standard Media Library, visitors receive files from the CDN domain, the WordPress server spends less time serving static assets, and the administrator can track offload status and download objects back when necessary.

Preparation

1. Create a backup of the database and the wp-content/uploads folder.
2. Prepare a bucket or Space with a clear name, separate from test projects.
3. Create credentials only for the required provider and store the secrets in a secure location.
4. Set up a system cron or confirm that WordPress cron runs regularly.
5. Build a test page that includes a standard image, a gallery, a cover block image, a downloadable file, a product page, or any other content type that is important for the site.

Configuration Steps

1. Install and activate the plugin, then open Settings -> Offload Media.
2. Select the storage provider and save the authentication method using the official quick start guide for that provider.
3. Select an existing bucket or create a new one from the plugin interface, if that fits your workflow.
4. Leave Remove Local Media turned off during the first phase.
5. Upload a new test file to the Media Library and confirm that it is offloaded.
6. Configure the delivery provider. For an S3 setup with a CDN, choose CloudFront or another proven CDN, then enter the custom domain after DNS and certificate setup are complete.
7. Check the URL Preview, save the settings, and open the test page in the browser.
8. Start migrating the existing Media Library only after the new test file has been validated successfully.

Verifying the Result

Open the public test page and use your browser's developer tools. In the Network tab, locate the image or file. The URL should point to the selected delivery domain. The response status should be successful, the content type should match the file, and the HTML should no longer contain the old local URL for an item that has already been migrated.

Then check the admin area. Open the Media Library in grid mode, view the file card, and, if available, the offload status metabox. Test not only viewing, but also editing: crop an image, replace a file through a supported plugin, insert it into a post, and save the block. If the site uses WooCommerce, open a product that includes an image, a gallery, and a digital file, then perform a test download through an allowed workflow.

Nuance: When to Enable Local File Removal

After a successful migration, you can consider enabling Remove Local Media. But it should only be turned on after all real-world workflows have been tested. If you use an image optimizer, additional image size generation, PDF previews, a gallery plugin, a page builder, or an import plugin, test them first with files that have already been offloaded. If everything works, enable local file removal for new files and monitor the site. Bulk removal of existing local files is better handled during a separate maintenance window.

How to Validate the Result After Setup

WP Offload Media should be verified at three levels: WordPress can see the file, the bucket contains the object, and the visitor receives the correct URL. If you test only one layer, you can miss the real issue. For example, the file may exist in the bucket, but the CDN cannot access it. Or the page may show a CDN URL, but the editor cannot process a remote-only file. Or everything works on the homepage, but older posts with serialized content are not being rewritten the way you expected.

Checking Inside the Media Library

Open several file types: a normal image, an image with multiple generated sizes, a document, a file attached to a product, an image from an ACF field, or a file used in a page builder block. Check whether the offload status appears, whether the remote URL is correct, whether the file can be downloaded, and whether the interface shows any errors. If the plugin provides filters by offload location or access level, use them for spot checks.

Checking the Public Side of the Site

On the frontend, inspect both the HTML source and the Network tab. The URL for an image in content, a block background image, a post thumbnail, and a gallery item may be generated in different ways. If some files are still local, that is not always a problem: the file may not have been migrated yet, may be excluded by another plugin, or may be stored in a location that does not belong to the standard WordPress Media Library.

For CDN delivery, inspect the response headers. Different providers expose different headers, but you can usually identify edge delivery, cache status, or the CDN domain. Do not judge performance by a single request: the first one may warm the cache, while repeated requests will be faster. Use several pages and separate performance tools for evaluation, but remember that media offloading does not replace page caching.

Checking SEO and Media Indexing

If the media domain changes, it is important that URLs remain stable, HTTPS works without warnings, and images are not blocked by robots rules or bucket policies. A custom subdomain on the site's main domain usually looks cleaner than a raw bucket URL. But the subdomain alone does not guarantee any SEO improvement. What really matters is speed, availability, correct HTML, alt text, image dimensions, and the absence of broken links.

Compatibility with the Theme, Cache, WooCommerce, and the Editor

WP Offload Media uses standard WordPress attachment and URL mechanisms, so in many cases it works without manual changes. But the most common conflicts appear where another plugin expects a local file, reads the path from wp-content/uploads directly, or tries to rewrite CDN URLs on its own.

Caching Plugins and CDN Settings

The plugin is not a page cache. It can be used alongside WP Rocket, W3 Total Cache, server-side caching, Varnish, or FastCGI cache. But if your caching plugin also has a setting like "CDN for Media Library," it should usually be turned off to avoid double URL rewriting. If you are using the Assets Pull addon, check in the same way whether another plugin is rewriting CSS, JavaScript, and fonts to a different domain.

After changing the delivery domain, clear the page cache and CDN cache if needed. Otherwise, you may keep seeing old URLs in cached pages and mistakenly assume the configuration did not work. Test in a private window or with a cache-bypass parameter, if that is acceptable for your site.

Galleries, Sliders, and Image Optimizers

Galleries and sliders often rely on extra image sizes, lazy loading, their own tables, or custom metadata. If local copies are preserved, those plugins usually handle offloading more smoothly. If local file removal is enabled, it becomes important to verify whether the specific plugin can work with remote-only attachments. The official documentation explicitly warns that compatibility issues are much more common once files are removed from the server.

Image optimizers should be run in a predictable order. One safe option is optimization during upload, followed by offloading. Another is to use an integration officially supported by the product. If the optimizer regenerates files after offloading, make sure the updated sizes are also copied into the bucket and that URLs are not still pointing to old versions.

WooCommerce, Digital Products, and Private Delivery

For WooCommerce, two different scenarios matter. Product images are usually public, and their job is to load quickly on product pages, archive pages, and in the cart. Digital product files may be private, and for those the priorities are access control, signed URLs, and avoiding direct public links. WP Offload Media supports WooCommerce integration in the extended version of the product, but each store still needs to be tested specifically: download behavior after an allowed action, retry behavior after the link expires, what happens when the order status changes, and how caching affects the flow.

ACF, Elementor, Divi, WPML, and Other Integrations

The official product page and documentation list supported integrations, including Advanced Custom Fields, WooCommerce, Easy Digital Downloads, Elementor, Divi Builder, WPML, Enable Media Replace, EWWW Image Optimizer, MetaSlider, and BuddyBoss. That does not mean every custom site is automatically safe. If the theme stores image URLs in custom fields, serialized content, or nonstandard tables, check those areas separately.

The main practical compatibility test is this: the editor can select the file, the frontend shows the correct URL, image size generation does not break, replacing an image updates the remote object, and disabling delivery rewriting does not leave the site without files. If all of those checks pass, the configuration is close to production-ready.

Safe Customization: Making New Offloaded Files Private by Condition

In most projects, file visibility is best managed through the Media Library interface and the private delivery settings. But there are cases where a developer needs new offloaded objects to be private by default, or only under certain conditions: protected learning materials, digital product files, or documents in a membership section. For that, the official documentation describes the as3cf_upload_object_key_as_private filter.

Do not add this code just for neatness. It changes object access at upload time, so it should only be used once private file delivery is already configured and signed URLs have been tested. If you make every new object private on a normal media-heavy site without CloudFront private media or a similar delivery model, public images may stop loading.

/**
 * Makes new offloaded objects private.
 * Use only after private delivery is configured and tested on staging.
 */
function site_as3cf_upload_object_key_as_private( $is_private ) {
    return true;
}
add_filter( 'as3cf_upload_object_key_as_private', 'site_as3cf_upload_object_key_as_private' );

The best place for this code is a child theme, a small utility plugin, or a safe snippet manager that can be disabled quickly. After adding it, upload a test file, check its access status in the Media Library, open the public page, and confirm that the private file is accessible only through the allowed workflow. Rollback is simple: disable the snippet and upload a new test file. Objects that were already uploaded need to be switched back through Media Library actions or the product's tools if their status needs to change.

Common Problems and Troubleshooting

WP Offload Media issues are most often caused not by offloading itself, but by external dependencies: bucket permissions, Object Ownership, Block All Public Access, the CDN domain, cron, Basic Auth, local files, or conflicting CDN rewriting. The best way to troubleshoot is by symptoms, not by randomly flipping settings.

Files Uploaded Successfully, but the Site Shows Broken Images

Symptom: the file appears to be migrated in the Media Library, but the public page shows an empty space, a 403, a 404, or a mixed-content error. A likely cause is that the delivery provider cannot access the bucket, the custom domain points to the wrong place, the CDN certificate is not ready, or strict S3 permissions are enabled without a proper CloudFront setup.

Check the raw file URL, the CDN URL, and the Network response. If the raw bucket URL is blocked but CloudFront is configured correctly, that may be expected. If both the bucket URL and the CDN URL are blocked, go back to the distribution settings, origin access, Block All Public Access, and Object Ownership. Do not make the entire bucket public unless you fully understand the delivery model you are using.

The Offload Tool Is Stuck or Migrates the Media Library Very Slowly

Symptom: the percentage does not change, background tools sit idle for a long time, or only part of the files are migrated. Likely causes include inconsistent cron execution, Basic Auth on staging, blocked internal HTTP requests, PHP limits, or network errors when connecting to the storage provider.

Check cron events, wp-cron.php availability, PHP logs, and any protection rules in place. On a locked staging site, configure an exception for internal requests or temporarily use another way to trigger cron. If the migration is very large, run it during a quiet period and avoid launching multiple parallel processes.

The Editor or Gallery Broke After Enabling Remove Local Media

Symptom: the frontend may still work, but the editor, slider, optimizer, thumbnail generation, or a theme block complains that the file is missing. The usual reason is that another plugin needs a local file path rather than a remote URL.

Turn off local file removal, download the offloaded files back to the server using the product's tool, and run the test again. Then check the documentation for the conflicting plugin. If there is no compatibility path, keep local copies or change the image-processing workflow. Saving disk space should not matter more than a stable Media Library.

The Custom Domain Is Saved, but URLs Are Not Changing

Symptom: the CDN domain is configured in settings, but the HTML still contains raw bucket URLs or local links. Possible causes include page cache, the delivery provider not being selected, Deliver Offloaded Media being turned off, some files not being offloaded yet, or the content storing URLs in a nonstandard location.

Clear the page cache, review the URL Preview, open a newly uploaded file, and compare it with an older one. If the issue only affects older posts, verify that those attachments were actually migrated and that the plugin supports URL rewriting in that particular storage location.

Warning About Object Ownership or Block All Public Access

Symptom: the settings show a warning about bucket security, and files do not open through the selected delivery method. The cause is that the S3 access model does not match the delivery provider. With CloudFront, you can build a locked-down delivery model. Without CloudFront or without a bucket policy, raw URLs and some third-party CDNs may not be able to access the objects.

Define the scenario you actually need: CloudFront with a private bucket, raw S3 URLs, a third-party CDN, or private signed URLs. Then configure Block All Public Access and Object Ownership for that exact scenario. If you are unsure, test on a separate bucket rather than on the live Media Library.

When It Is Better to Roll Back a Setting

A rollback makes sense if changes result in widespread 403 or 404 image errors, a stalled background migration, editors being unable to work with media, or digital files becoming accessible in ways they should not be. First disable the questionable layer: local file removal, custom domain, delivery rewriting, or privacy for new offloads. Then restore local files, clear caches, and test a single page. Do not delete Media Library records or bucket objects until you understand the root cause.

When WP Offload Media Is the Right Choice

WP Offload Media is worth using when the task is clear: move the WordPress Media Library into cloud storage, manage offload status from the admin area, serve files through a CDN, and retain control over the provider, bucket, delivery domain, and private objects. This is an infrastructure plugin for sites where media already affects disk usage, delivery speed, portability, or system architecture.

It is especially useful for projects with large media libraries, multiple environments, WooCommerce or EDD files, media portals, membership sites, and teams that are ready to maintain a bucket, a CDN, and cron. For a small site with no disk or performance pressure, it usually makes more sense to start with caching, image optimization, and a hosting review.

Before rolling it out, define your working model: which provider, which bucket, whether a CDN is needed, whether a custom domain is needed, whether local copies will remain, who is responsible for bucket backups, and what rollback will look like. If you have those answers, you can move on to testing and download WP Offload Media from the download block on the product page.

The final check is simple: a new file uploads through WordPress, appears in the bucket, is served from the correct domain, can be edited without errors, older attachments migrate through the background tool, and disabling a questionable setting does not leave the site without images. If that chain holds, WP Offload Media becomes more than just an "S3 plugin" and turns into a proper media delivery layer in your WordPress architecture.