PUT Object - Copy

You can use the S3 PUT Object - Copy request to create a copy of an object that is already stored in S3. A PUT Object - Copy operation is the same as performing a GET and then a PUT.

Resolving conflicts

Conflicting client requests, such as two clients writing to the same key, are resolved on a latest-wins basis. The timing for the latest-wins evaluation is based on when the StorageGRID system completes a given request, and not on when S3 clients begin an operation.

Object size

StorageGRID supports objects up to 5 TB in size.

Note: The maximum size for objects that can be replicated to a destination bucket by the CloudMirror replication service is 625 GiB (671,088,640,000 bytes). Objects that match the filtering criteria in the CloudMirror replication configuration XML will not be ingested if they are larger than this size.

UTF-8 characters in user metadata

If a request includes (unescaped) UTF-8 values in the key name or value of user-defined metadata, StorageGRID behavior is undefined.

StorageGRID does not parse or interpret escaped UTF-8 characters included in the key name or value of user-defined metadata. Escaped UTF-8 characters are treated as ASCII characters:

Supported request headers

The following request headers are supported:

Unsupported request headers

The following request headers are not supported:

Storage class options

The x-amz-storage-class request header is supported, and affects how many object copies StorageGRID creates if the matching ILM rule specifies an Ingest Behavior of Dual commit or Balanced.

Request headers for server-side encryption

If you use server-side encryption, the request headers you provide depend on whether the source object is encrypted and on whether you plan to encrypt the target object.

Using x-amz-copy-source in PUT Object - Copy

If the source bucket and key, specified in the x-amz-copy-source header, are different from the destination bucket and key, a copy of the source object data is written to the destination.

If the source and destination match, and the x-amz-metadata-directive header is specified as REPLACE, the object’s metadata is updated with the metadata values supplied in the request. In this case, StorageGRID does not re-ingest the object. This has two important consequences:
  • You cannot use PUT Object - Copy to encrypt an existing object in place, or to change the encryption of an existing object in place. If you supply the x-amz-server-side-encryption header or the x-amz-server-side-encryption-customer-algorithm header, StorageGRID rejects the request and returns XNotImplemented.
  • The option for Ingest Behavior specified in the matching ILM rule is not used. Any changes to object placement that are triggered by the update are made when ILM is re-evaluated by normal background ILM processes.

    This means that if the ILM rule uses the Strict option for ingest behavior, no action is taken if the required object placements cannot be made (for example, because a newly required location is unavailable). The updated object retains its current placement until the required placement is possible.


If the source bucket is versioned, you can use the x-amz-copy-source header to copy the latest version of an object. To copy a specific version of an object, you must explicitly specify the version to copy using the versionId subresource. If the destination bucket is versioned, the generated version is returned in the x-amz-version-id response header. If versioning is suspended for the target bucket, then x-amz-version-id returns a null value.