I set up replication between my buckets, but new objects aren't replicating. How can I troubleshoot this?

Last updated: 2021-12-03

I set up cross-Region replication (CRR) or same-Region replication (SRR) between my Amazon Simple Storage Service (Amazon S3) buckets. However, objects aren't replicating to the destination bucket. How can I fix this?

Resolution

To troubleshoot objects that aren't replicating to the destination bucket, check the following:

Tip: As you work through the troubleshooting steps, be sure to test replication after each configuration change by uploading an object to the source bucket. It's a best practice to make one configuration at a time so that you can identify the problem with the replication setup.

When the objects were added to the source bucket

After replication is configured on the source bucket, only new objects are replicated to the destination bucket. Objects that were in the source bucket before you configured replication aren't automatically replicated.

To trigger replication of existing objects to the destination bucket, run the cp command to copy the existing objects back into the source bucket. For example, the following command copies objects in source-AWSDOC-EXAMPLE-BUCKET back into source-AWSDOC-EXAMPLE-BUCKET:

aws s3 cp s3://source-AWSDOC-EXAMPLE-BUCKET s3://source-AWSDOC-EXAMPLE-BUCKET --recursive --storage-class STANDARD

Existing object replication is an extension of the existing Amazon S3 Replication feature and includes all the same functionality. For information about enabling existing object replication for your account, see Replicating existing objects between S3 buckets.

The replication status of the objects

Check the replication status of the objects that aren't replicating. If there is no replication status metadata on the objects, then it's likely that the prefix or tag filter must be reviewed. If you set a prefix filter for the subset of objects to replicate, then verify that the prefix in the source bucket is correct. If you set a tag filter, then the tag must be applied at object creation. If the object already exists in the bucket and you add a tag, then replication won't be triggered by the addition of the tag.

If the replication status is PENDING, then Amazon S3 is still processing the replication. Most objects replicate within 15 minutes, but sometimes replication can take a couple of hours or more. Larger objects can take longer to replicate. To monitor replication metrics (such as the maximum replication time), you can enable S3 Replication Time Control (S3 RTC).

If the replication status is REPLICA, then the object is a replica of an object from another source bucket. Objects in the REPLICA state aren't further replicated.

If the replication status is FAILED, then proceed with the following checks.

Required permissions for replication

If the source and destination buckets belong to the same AWS account, then confirm that the replication role's trust policy and access policy grant the minimum required permissions.

If the source and destination buckets belong to different accounts, then confirm that:

For cross-account replication, if you configured the owner override option, then confirm that:

If you enabled replication of objects encrypted by an AWS Key Management Service (AWS KMS) customer managed key, then confirm that:

If S3 Bucket Key is enabled on the source or destination bucket, the encryption context will be the Amazon Resource Name (ARN). The encryption context will not be the object ARN. For example, the encryption context will be arn:aws:s3:::bucket_ARN.

Therefore, make sure to update your AWS Identity Access Management (IAM) policies to use the bucket ARN for the encryption context, like this:

"kms:EncryptionContext:aws:s3:arn": [
     "arn:aws:s3:::SOURCE_BUCKET_NAME"
     ]
"kms:EncryptionContext:aws:s3:arn": [
     "arn:aws:s3:::DESTINATION_BUCKET_NAME"
     ]

If S3 Bucket Key isn't enabled on the source or destination bucket, then no changes are required to the encryption context in the IAM policies.

Ownership of objects in the source bucket

If objects in the replication source bucket are owned by another AWS account, then the required replication permissions aren't applied correctly and replication fails for those objects. The account that owns the objects must explicitly grant full control to the replication source account. For instructions on granting full control of objects, see Why can't I access an object that was uploaded to my Amazon S3 bucket by another AWS account?

The source object's access control list (ACL) and the destination bucket's Block Public Access settings

If the source object's ACL allows public read access, and the destination bucket blocks public access granted by ACLs, then replication fails. Depending on your use case, modify either the source object's ACL or the destination bucket's settings so that they are compatible.