Troubleshooting

Your provider refused the keys. Usually the secret was pasted incorrectly, or the key doesn't exist in this account. Offloft shows "The Access Key ID wasn't recognized." or "The Secret Access Key doesn't match the Access Key ID." Paste both again, or create a new key.

1. 1The name. Copy it from your provider's dashboard.
2. 2The region. Choose the one the bucket was created in.
3. 3The endpoint, for providers that use one. It must be the right server.
4. 4The Cloudflare account. An R2 bucket must belong to this account. For a bucket in the EU or FedRAMP jurisdiction, choose that jurisdiction.

The bucket exists, but in a different region from the one in Offloft's settings. Your provider returned AuthorizationHeaderMalformed, PermanentRedirect or IllegalLocationConstraintException. Open Settings → Connection, choose the region the bucket was created in, then test again. A bucket's region can't be changed.

Your provider returned ExpiredToken or InvalidToken, which means the key is no longer valid. Create a new access key at your provider, paste it in Settings → Connection, and run the connection test. Use a long-lived key limited to this bucket, not temporary session credentials, so this doesn't happen again.

Storage providers reject requests when the sending server's clock is too far off, usually with RequestTimeTooSkewed. Offloft shows "Your server's clock is wrong, so the provider rejected the request." Ask your host to synchronize the server clock (NTP), then run the connection test again. Your keys are fine.

Bucket names are shared by everyone on a provider, so someone else already has this one. Add something of your own, like your site name, and try again: my-site-media rather than media. Your provider returned BucketAlreadyExists. It isn't a problem with your keys or your account.

A bucket name needs 3 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit. Avoid periods, because they break secure (https) addresses. Your provider returned InvalidBucketName if Offloft shows "That isn't a valid bucket name." For example, my-site-media is fine.

Your provider returned TooManyBuckets, because this account can't hold another bucket. Delete a bucket you no longer use, or choose an existing bucket. Some providers can raise the limit if you ask them. Offloft only needs one bucket per site, and it can share a bucket by using a different path.

If your provider is busy or down, you usually don't need to do anything. Offloft notices, pauses uploads without using up their retries, shows an issue, checks again on its own and continues where it stopped. Your site keeps showing its media. In a test, wait a minute and try again.

The delivery check loads a small test image from your public address, as a visitor's browser would. If it fails, the address doesn't lead to a public copy of your file yet. Your site keeps loading images from your server meanwhile. The message tells you which part to fix.

1. 1The delivery check. Open Settings → Delivery. Offloft serves nothing from the cloud until it passes.
2. 2Rewrite media URLs. It must be on, also in Settings → Delivery.
3. 3This file's state. Open it under Files. A file that isn't verified loads from your server. See file states.
4. 4Your existing library. Files from before setup go up only when you run Offload everything.
5. 5Exclusions. Check for excluded items and skipped file types.
6. 6Your page cache. Clear it. A cached page keeps the addresses it was saved with.
7. 7Saved addresses. If a theme stored a full image address, see replace URLs.

A thumbnail is usually missing because WordPress never created that size, or another plugin deleted it. Offloft flags it under Issues as "Image size missing", and the fix creates the size, uploads it and checks it. Your site keeps showing a working copy. A size missing only from the bucket shows as "Cloud copy missing".

Uploads run as WordPress background tasks. If they aren't moving, WP-Cron is probably off or being blocked, and Offloft shows "Background tasks aren't running". Click Run now to process what's waiting, and add a real cron job so they keep running. Your site keeps working from local files meanwhile.