How to Copy S3 Objects and Fix Copy Errors

The S3-compatible CopyObject operation enables you to copy an existing file from one location to another in the object storage. It can be used to copy an object, to copy an object to another Space or to change the object key of a file.

API Based Object Copy for Cyberin S3 Object Store Copying an object with the API requires the correct source key, destination path, regional endpoint and access permissions.

This article explains how to copy an object by using the AWS CLI, and how to troubleshoot common copy errors.

Step 1: Copy an Object Using the AWS CLI

Use the copy-object command to copy a file.

aws s3api copy-object \
  --bucket DESTINATION_SPACE_NAME \
  --key destination/report.pdf \
  --copy-source SOURCE_SPACE_NAME/documents/report.pdf \
  --endpoint-url https://YOUR_REGION.digitaloceanspaces.com

Replace the placeholders as follows:

For example, this command copies documents/report.pdf from one Space to backups/report.pdf in another compatible Space.

The source key must match the stored object path exactly, including capitalization and file extension.

Step 2: Verify the Copy

Run the command and check the response against the metadata of the copied object.

You can also check target object by:

aws s3api head-object \
  --bucket DESTINATION_SPACE_NAME \
  --key destination/report.pdf \
  --endpoint-url https://YOUR_REGION.digitaloceanspaces.com

If the command returns the object’s metadata, the destination object exists and you have access to it with your credentials.

As a further check compare the size of the destination file with the source file.

Step 3: Fix Common Copy Errors

Source object not found

Possible cause: Source Space name or object key is incorrect.

How to fix it:

  1. Verify the Origin of the Space Name.

  2. Please verify the object key and versioning prefix that you are using.

  3. head-object to verify source object exists

aws s3api head-object \
  --bucket SOURCE_SPACE_NAME \
  --key documents/report.pdf \
  --endpoint-url https://YOUR_REGION.digitaloceanspaces.com

If the source object does not exist, fix the key and try copying again.

Access denied

Possible cause: Access key denied to read the source object or write the destination object.

What you should do:

CopyObject requires Read/Write/Delete (Objects) permission on DigitalOcean Spaces.

Incorrect destination path

Possible cause: The target key has an invalid file name or folder prefix.

How to fix it:

Review the --key value. For example:

--key backups/report.pdf

This specifies the destination object key backups/report.pdf It doesn’t create a traditional filesystem directory, the slash is part of the object key.

Set the destination key and run the command again.

Copy fails between regions

Possible cause: Source & Destination Spaces are in different clusters/zones

How to fix it:

Please review the service needs and locations for the two spaces. DigitalOcean Spaces does not support CopyObject cross region/cluster.

If the objects cannot be copied directly, download the source object with a supported transfer workflow, and then upload it to the destination, if the source and destination storage types support those operations.

Copy succeeds but the metadata is unexpected

Possible Cause The copy operation retained the source metadata and you wanted different values or the destination metadata was not set up as you expected.

How to repair it?

Check destination object with head-object. If you need to change metadata, use the supported copy and metadata directives for your S3-compatible client and check the resulting object after the operation.

Important Considerations

Additional Resources