This topic describes common issues you may encounter when using ossutil and their solutions.
Starting from ossutil v1.6.16, you can use ossutil as the command name directly, regardless of the operating system. For versions earlier than v1.6.16, you must use the operating system-specific executable name. For more information, see ossutil command reference.
Does ossutil support signature V4?
Yes, ossutil V1.7.12 and later support signature V4. For more information about signature V4, see Include a V4 signature in the Authorization header (recommended).
In v1.7.12 and later, ossutil adds the --sign-version and --region options. For example, the following command creates a bucket in the China (Hangzhou) region:
./ossutil64 --sign-version v4 --region cn-hangzhou mb oss://examplebucketIs object synchronization supported for Infrequent Access and Standard objects?
Yes, object synchronization is supported for Infrequent Access (IA) and Standard objects. For more information about synchronization, see Overview.
How do I prevent overwriting an object with the same name?
To prevent overwriting an existing object with an uploaded object that has the same name, add the -u option to your ossutil command.
Why do I see a 'skip' message when uploading an object with the -u option?
Analysis: When you use the -u option, ossutil compares the object you are uploading with existing objects in the destination bucket.
If an object with the same name already exists in the bucket, and its last modified time is the same as or later than the object you are uploading, ossutil skips the upload. The object is uploaded only if its last modified time is later than the existing object. Therefore, the skip message is normal when you use the -u option to upload an object.
Solution: Safely ignore this message if you confirm that the existing object in the bucket is the version you want to keep.
Why do I get an HTTP 403 error when restoring an object?
Cause: An HTTP 403 error can occur for the following reasons:
If you perform the operation as a RAM user, the user may not have the required permissions for the operation on the object.
The object has been blocked by OSS due to prohibited content.
Solutions
Insufficient RAM user permissions: Grant the required permissions to the RAM user.
Content violation: Delete or ignore the blocked object.
Why can't I delete a bucket that appears empty after running the ls command?
Cause: When you run the ls command without any options, it does not list incomplete multipart upload parts or previous object versions (in versioned buckets). If a bucket contains such items, it is not truly empty and cannot be deleted with only a rm command.
Solutions
Deleted buckets and objects cannot be restored. Exercise caution when you run the command.
Delete any parts and previous versions first, then delete the bucket.
Delete parts and previous object versions.
List and delete incomplete multipart upload parts:
./ossutil64 ls oss://bucket1 -m ./ossutil64 rm -m oss://bucket1 -rList and delete all object versions (for versioned buckets):
./ossutil64 ls oss://bucket1 --all-versions ./ossutil64 rm oss://bucket1 --all-versions -r
Delete the bucket.
./ossutil64 rm oss://bucket1 -b
Forcibly delete the bucket.
If versioning is not enabled for the bucket, run the following command:
./ossutil64 rm oss://bucketname -abrfIf versioning is enabled for the bucket, run the following command:
./ossutil64 rm oss://bucketname -abrf --all-versions
Why does the upload or download progress exceed 100%?
Cause: When you upload or download an object larger than 100 MB, ossutil uses resumable transfer by default. It stores checkpoint information in a .ossutil_checkpoint directory. If multiple ossutil instances run concurrently on the same machine, they may share this default checkpoint directory. When one ossutil instance completes its task, it deletes the .ossutil_checkpoint directory, which can corrupt the state of other ongoing transfers, causing their progress to display incorrectly (example: exceeding 100%) and fail.
Solutions
Stop the failed task and restart the upload or download.
When running concurrent tasks, add the --checkpoint-dir option to the cp command to assign a unique checkpoint directory for each task. Example:
./ossutil64 cp oss://bucket1/myphoto.jpg /dir --checkpoint-dir checkpoint
Why are multiple requests logged when downloading a single object?
This can happen for two reasons:
Automatic retries: ossutil automatically retries failed or exceptional requests. By default, it retries up to 10 times.
Range requests: For objects larger than 100 MB, ossutil uses range requests to download the object in parts. Each part is a separate request, resulting in multiple log entries for a single download operation.
What should I do if a large object download is interrupted?
Common causes of download interruptions:
A download of a large file may require a long period of time to complete, causing an interruption of the download.
In this case, the interruption is caused by network bandwidth limits or unstable network connections.
A download of a large file experiences an end-of-file (EOF) error, causing an interruption of the download.
In this case, the interruption is caused by lost network connections or slow disk read/write performance that does match the download speed.
Solution: Use resumable download.
Specify a checkpoint directory using the --checkpoint-dir option. If the transfer is interrupted, ossutil can use the information in this directory to resume from where it left off.
./ossutil64 cp examplefile.txt oss://examplebucket/desfolder/ --checkpoint-dir localfolder/For more information about how to configure --checkpoint-dir, see Command syntax.
Why do I get the Error: accessKeyID and ecsUrl are both empty error?
Cause: No configuration file was found in the home directory.
Solutions
Before running ossutil commands, create a configuration file in your home directory. For more information, see Install ossutil.
Explicitly specify the path to your configuration file by using the -c option with each command. For example:
./ossutil64 cp examplefile.txt oss://examplebucket/destfolder/ -c /home/admin/.ossutilconfig
Why is charset=utf-8 added to the Content-Type of uploaded objects?
Cause: When you upload an object, ossutil determines the object's 'Content-Type' by looking up the Multipurpose Internet Mail Extensions (MIME) type associated with its file extension. It uses the standard MIME library of Go. This library automatically appends charset=utf-8 for text-based MIME types. For example, for an .htm file, it returns text/html; charset=utf-8.
Solution: Upgrade ossutil to V1.7.14 or later. You can upgrade by reinstalling it. For more information, see Install ossutil.
Can I use ossutil to query the size of a directory?
Yes, you can run the du command. This command calls the ListObjects API operation to get information about all objects under the specified prefix and then calculates the total size of the directory. If the directory contains a large number of objects, this operation can take a long time.
For more information, see du.
How do I generate a signed URL that contains a custom domain name?
Configure a custom domain name for the bucket.
For more information, see Configure a custom domain name.
Run the sign command to generate a signed URL.
For more information, see sign.
Can I sort the results when listing objects with ossutil?
No, result sorting is not supported for ossutil-based object query.
Why do I get a 'no such host' error when running ossutil commands?
Cause: The endpoint is invalid.
Solution: Specify a valid endpoint by using the -e option, or store the correct endpoint in your configuration file. The -e option specifies the endpoint for the bucket's region, such as -e oss-cn-shanghai.aliyuncs.com. Do not include any extra characters in the endpoint string. For a list of endpoints, see Regions and endpoints.
How am I charged for the du command?
The du command incurs API request fees. If --all-versions is not specified in the du command, the ListObjects operation is called. If --all-versions is specified in the du command, the ListObjectVersions operation is called. The command also calls the ListMultipartUploads operation. For more information, see API operation calling fees.
If the bucket contains parts from incomplete multipart uploads, fees for ListUploadedParts requests will also apply.