Skip to content
Signalcraft
日本語

← Back to Signalcraft

Safely Diagnose Cloudflare R2 and rclone Operations

Safely Diagnose Cloudflare R2 and rclone Operations

The first thing to understand when operating Cloudflare R2 with rclone is that the target is an object-key prefix, not a folder.

A directory-looking path is a common part of object keys.

If that distinction is vague, move and delete operations become easy to mis-target.

Another trap is a 403 from GetBucketVersioning.

R2’s S3 API compatibility table describes that API as unimplemented.

A 403 from one API therefore needs to be separated from the conclusion that the whole credential is invalid.

Fix the connection assumptions from official documentation

Cloudflare’s rclone example uses Cloudflare as the S3 provider and an account-specific R2 endpoint.

The minimal shape is:

[r2]
type = s3
provider = Cloudflare
access_key_id = ...
secret_access_key = ...
endpoint = https://ACCOUNT_ID.r2.cloudflarestorage.com
acl = private

Confirm the remote name, account ID, target bucket, and credential separately.

Give the credential only the permissions required for the target bucket and operations.

The rclone configuration may store secrets in plaintext, so check configuration encryption and operating-system permissions.

Never add the configuration file or access keys to a repository.

A token that cannot enumerate a bucket may cause rclone’s bucket check to fail.

Only then consider no_check_bucket = true, and first verify that the API token permissions match the target bucket.

Classify 403 responses by operation

The same status code can mean different things depending on the S3 operation.

Failed operation First check
List buckets Can the token enumerate buckets?
List objects Does it have permission for the bucket and prefix?
Upload Does it have Object Write permission?
Delete Does the Write permission include deletion?
Get versioning Is the API unimplemented in R2?

The R2 S3 API compatibility table marks GetBucketVersioning as unimplemented.

If listing and copying work, do not interpret a 403 only on the versioning check as a complete connection failure.

If listing, reading, and writing all fail, check the endpoint, bucket name, and token scope in that order.

Fix the prefix before the operation

Before deleting or moving anything, run commands that make the remote, bucket, and prefix explicit.

rclone lsf r2:my-bucket/archive/2026-08 --recursive
rclone size r2:my-bucket/archive/2026-08

Confirm that the listed keys are exactly the intended objects.

Do not use a bucket root or an empty prefix as a deletion target without an explicit review.

When shell variables or globs construct the target, print the expanded full remote path before continuing.

Separate copying and deletion before using move

The rclone move reference explains that a move may be a server-side operation or a copy followed by deletion depending on the conditions.

For important data, separate the stages so that failures are easier to resume.

# 1. Preview the copy
rclone copy r2:my-bucket/old-prefix r2:my-bucket/new-prefix --dry-run

# 2. Copy
rclone copy r2:my-bucket/old-prefix r2:my-bucket/new-prefix

# 3. Verify the destination
rclone check r2:my-bucket/old-prefix r2:my-bucket/new-prefix

# 4. Preview deletion
rclone purge r2:my-bucket/old-prefix --dry-run

# 5. Delete only the exact matching prefix
rclone purge r2:my-bucket/old-prefix

Do not delete the source prefix before reviewing rclone check.

If there is a difference, separate copy failure, wrong prefix, and insufficient permission before retrying.

Treat purge as a recovery decision

purge deletes everything below the specified prefix.

A one-character input error can therefore delete more than intended.

Because the S3-compatible versioning API is unimplemented in R2, do not assume that deletion can be easily restored from an S3 version.

Back up important objects to another bucket, account, or storage service.

Preserve evidence after the operation

Record the following in an operation log:

  • Execution time
  • rclone version
  • Source and destination
  • Object and byte counts before and after
  • The result of rclone check
  • Who deleted what and why

Do not put access keys, secret keys, or signed URLs into logs.

R2’s S3 compatibility means that many tools can be used.

It does not mean that every AWS S3 API behaves identically.

Check the compatibility table first, fix the prefix explicitly, and separate copy from deletion.

References