I set up replication between my buckets, but new objects aren't replicating. How can I troubleshoot this?
Last updated: 2020-06-18
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?
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. Don't make several configuration changes at the same time because it will be difficult to 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, you can 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
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 fixed. 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, 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.
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 replicated further.
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:
- The replication role in the source account has a trust policy and an access policy that grant the minimum required permissions.
- The destination bucket's policy grants the source account the permissions to perform the required replication actions.
For cross-account replication, if you configured the owner override option, then confirm that:
- The replication role in the source account has the permission to change object ownership.
- The destination bucket's policy grants the source account the permission to change object ownership.
If you enabled replication of objects encrypted by an AWS Key Management Service (AWS KMS) customer master key (CMK), then confirm that:
- For same-account replication, the replication role must have the required permissions to use the AWS KMS key.
- For cross-account replication, the replication role must have the required permissions to use the AWS KMS key. Additionally, the CMK key policy must grant the source account permissions to use the key.
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 won't apply 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 will fail. Depending on your use case, modify either the source object's ACL or the destination bucket's settings so that they are compatible.