Most Amazon S3 Storage problems are one of three things: the access keys can’t do what the plugin needs, a file never made it to the bucket, or the download method doesn’t suit the file. Find your symptom below, or search this page for the message you see.
Before you start, tick Debug mode under WooCommerce » Settings » S3 storage and repeat the thing that failed. The plugin then writes each step to WooCommerce » Status » Logs, which usually names the cause. Turn it off again when you’re done.
Connection messages
The plugin tests your keys by listing your buckets. While the keys are saved but the test fails, every admin page shows an error that starts "A connection to Amazon S3 could not be initialized" (or Cloudflare R2), and the rest of the settings stay hidden.
"the access key ID is not valid"
The full message is "A connection to Amazon S3 could not be initialized: the access key ID is not valid. Check your credentials." The provider doesn’t recognize the access key ID. Copy it again, without spaces, and make sure the key hasn’t been deactivated or deleted. With constants, check the constant names for your provider (see Credentials location).
"the secret access key does not match the access key ID"
The full message is "A connection to Amazon S3 could not be initialized: the secret access key does not match the access key ID. Check your credentials." The secret belongs to a different key, or was copied incompletely. Paste both values from the same key pair again. If you no longer have the secret, create a new key; providers show it only once.
"these credentials do not have permission to list buckets"
The full message is "A connection to Amazon S3 could not be initialized: these credentials do not have permission to list buckets. Update their permissions and try again." The keys work, but they can’t list buckets, which the plugin needs to connect:
- Amazon S3: add
s3:ListAllMyBucketson"Resource": "*"to the IAM user’s policy (see Set up Amazon S3 for your store). - Cloudflare R2: use a token with Admin Read & Write permission. Object-level tokens can’t list buckets (see Connect Cloudflare R2).
"Please check your credentials and verify that you have the right permissions to manage S3"
The full message is "A connection to Amazon S3 could not be initialized. Please check your credentials and verify that you have the right permissions to manage S3." The provider didn’t say exactly why. Check, in order:
- For Cloudflare R2, that Endpoint is your account’s S3 API address (
https://<account-id>.r2.cloudflarestorage.com, or your jurisdiction’s endpoint). - That the access key ID and secret are both from the same, active key.
- That your server’s clock is correct. Requests signed with a clock more than a few minutes off are rejected.
- That your host allows outgoing connections to your provider. Debug mode logs the underlying error as "Cannot connect to S3".
The connection stopped working after moving or cloning the site
Keys saved in the database are encrypted with your site’s WordPress security keys (salts). A migration, a staging copy or a security plugin that changes those salts makes the saved keys unreadable. Paste both keys again and click Save changes, or store them as constants in wp-config.php instead.
The error notice stays after I fixed the keys
Open WooCommerce » Settings » S3 storage: the tab tests the connection each time it loads, and shows "Connected to Amazon S3." after you save. Elsewhere in the admin, the last result is remembered for up to an hour.
"OpenSSL encryption is not available on this server"
The full message is "Your S3 credentials cannot be saved or read because OpenSSL encryption is not available on this server. Ask your hosting provider to enable it, or store your credentials in configuration file constants instead." Ask your host to enable the PHP OpenSSL extension, or set Credentials location to the constants option and add the keys to wp-config.php.
"You have selected to use an experimental cloud service provider"
Cloud service provider is set to User defined (experimental), but the code snippet that names the provider isn’t active. Add it (see Connect other S3-compatible providers), or switch back to Amazon S3 or Cloudflare R2.
Creating a bucket from WooCommerce
These appear after you save with S3 bucket set to Create a new bucket…, as "Could not create bucket" followed by the bucket name and the reason.
"Bucket already exists. Please choose a unique name for your bucket."
Bucket names are unique across every AWS account, and someone (possibly you) already has this one. Pick another name, or create the bucket in the AWS console and select it from the list.
"An S3 error occurred. Please verify your S3 settings or try with another region."
AWS refused the request. The usual cause is a missing s3:CreateBucket permission on the IAM user. A name that breaks AWS’s naming rules, or a region your account hasn’t enabled, causes it too. Creating the bucket in the AWS console and selecting it from the list avoids all three.
"Please verify your credentials before creating a new bucket"
The full message starts "Not connected to Amazon S3." Fix the connection first (see Connection messages).
Offloading
A file stays on Queued or Processing
Uploads run as WooCommerce scheduled actions. Go to WooCommerce » Status » Scheduled Actions and search for s3_storage_upload_file. If the actions stay pending, WordPress cron isn’t running on your site; ask your host to set up a server cron job. If an action failed, its log says why. A very large file can also run out of time on the server mid-upload: link it with the S3 shortcode instead.
A file shows Failed
With Debug mode on, the log shows a line such as "Failed to upload file #123 to S3." followed by the reason. Common reasons are a missing s3:PutObject permission, a bucket that no longer exists, Transfer Acceleration turned on in WooCommerce but not on the bucket, and files larger than the 5 GB single-upload limit.
Saving the product again doesn’t retry a file that’s already marked Failed. Once you’ve fixed the cause, upload the file again as a new file: on the file’s row, click Choose file, upload it to the media library, select it, and click Update. The new file is queued like any other.
A file shows Not found
The file was offloaded, but it’s no longer in the bucket, so customers get the local copy. Either upload the file back to the bucket under the same object name (the status returns to Offloaded), or upload it to the media library again as a new file and select it on the product.
Customers download the wrong file
Each offloaded file is stored at the top level of the bucket under its file name. If two different files share a name, for example two manual.pdf files uploaded to different products, the later upload replaces the earlier one in the bucket, and both products deliver it.
Give each downloadable file its own file name. To fix products that already share one, rename one of the files on your computer, upload it to the media library as a new file, select it on its product, and click Update.
A file shows Unknown, Unhandled or Disabled
- Unknown or Unhandled: the file URL doesn’t point to a file in your media library (for example, an external URL), or the product hasn’t been saved since you added it. Only media library files are offloaded.
- Disabled: Enable under Automatic offloading is off.
Existing products aren’t offloaded
Offloading starts when you save a product in the product editor. Update each existing product (or variation) once to queue its files. Products created by imports or other plugins need the same.
Downloads
Files open in the browser instead of downloading
Set Download behavior to Force download under Product downloads. Links created before the change keep the old behavior until they expire.
A download link stops working
Signed links expire after the URL validity period (15 minutes by default), and an expired link shows an XML page from the provider saying the request has expired. Customers should start each download from their order email or My account » Downloads, which always produce a working link. Raise the period if customers download over slow connections.
Cloudflare R2 downloads are slow or show "File not found"
Update Amazon S3 Storage to version 3.5.5 or later. Earlier versions don’t apply Force redirect method to Cloudflare R2 (or Backblaze B2), so with WooCommerce’s default Force downloads method your server fetches each file from R2 and passes it on. That uses your bandwidth and can fail with WooCommerce’s "File not found" when the host doesn’t allow it. From 3.5.5, R2 downloads go straight to the signed link, as Amazon S3 downloads do.
If downloads still pass through your server after updating, check two things under WooCommerce » Settings » S3 storage: that Force redirect method is ticked, and that Endpoint holds your account’s S3 API address. The plugin recognizes R2 files by that address.
If you ticked Allow using redirect mode (insecure) as a last resort under WooCommerce » Settings » Products » Downloadable products to work around this, R2 downloads no longer need it.
Shortcode downloads fail
See the common issues in Link files with the S3 shortcode: "No file defined", NoSuchKey, region errors and AccessDenied.
"The approved download directories have been disabled while using this plugin."
This notice on WooCommerce » Settings » Products » Approved download directories is expected. While your access keys are saved, the plugin turns off WooCommerce’s approved directories check for the whole store, so you don’t need to add your bucket’s address there.
Get help
If you’re still stuck, contact support with:
- The plugin’s section of your system status report (WooCommerce » Status, section Amazon S3 Storage), which shows the provider, whether it’s configured and connected, and the download settings.
- The log lines from a failed attempt with Debug mode on. Remove access keys or other secrets before you share logs.