ossutil usage problems and solutions - Object Storage Service

This topic describes common issues when using ossutil and their solutions.

Note

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, see Include a V4 signature in the Authorization header (recommended).

ossutil V1.7.12 adds the --sign-version and --region options. The following command creates a bucket in the China (Hangzhou) region using signature V4:

./ossutil64 --sign-version v4 --region cn-hangzhou mb oss://examplebucket

Is object synchronization supported for Infrequent Access and Standard objects?

Yes, ossutil supports object synchronization for both Infrequent Access (IA) and Standard objects. For more information, see Overview.

How do I prevent overwriting an object with the same name?

Add the -u option to your ossutil command. With this option, ossutil skips the upload if an object with the same name already exists in the destination bucket and its last modified time is the same as or later than the object being uploaded.

Why do I see a 'skip' message when uploading an object with the -u option?

This is expected behavior. When you use the -u option, ossutil compares the last modified time of the object being uploaded against any existing object with the same name in the destination bucket. If the existing object's last modified time is the same as or later than the one being uploaded, ossutil skips it. The skip message is normal when you use the -u option to upload an object.

If the object in the bucket is the version you want to keep, safely ignore the skip message.

Why do I get an HTTP 403 error when restoring an object?

An HTTP 403 error on an object restore has one of two causes:

The RAM user running the operation lacks the required permissions.
OSS has blocked the object due to prohibited content.

To resolve the error:

Insufficient 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?

The ls command without options does not list incomplete multipart upload parts or previous object versions in versioned buckets. If a bucket contains either of these, it is not truly empty and cannot be deleted with rm alone.

To delete the bucket, use one of the following approaches:

Warning

Deleted buckets and objects cannot be restored. Exercise caution when running these commands.

Delete parts and previous versions first, then delete the bucket.
1. Delete incomplete multipart upload parts and all object versions.
  - List and delete incomplete multipart upload parts:
```
./ossutil64 ls oss://bucket1 -m
./ossutil64 rm -m oss://bucket1 -r
```
  - List and delete all object versions (for versioned buckets):
```
./ossutil64 ls oss://bucket1 --all-versions
./ossutil64 rm oss://bucket1 --all-versions -r
```
2. Delete the bucket.
```
./ossutil64 rm oss://bucket1 -b
```
Force-delete the bucket in a single command.
- If versioning is disabled:
```
./ossutil64 rm oss://bucketname -abrf
```
- If versioning is enabled:
```
./ossutil64 rm oss://bucketname -abrf --all-versions
```

Why does the upload or download progress exceed 100%?

For objects larger than 100 MB, ossutil uses resumable transfer by default and stores checkpoint information in a .ossutil_checkpoint directory. When multiple ossutil instances run concurrently on the same machine, they share this default checkpoint directory. When one instance finishes and deletes the .ossutil_checkpoint directory, it corrupts the checkpoint state for other ongoing transfers, causing their progress counters to display incorrect values (such as exceeding 100%) and the transfers to fail.

To fix this:

Stop the failed task and restart the upload or download.
When running concurrent tasks, assign a unique checkpoint directory to each using the --checkpoint-dir option with the cp command:
```
./ossutil64 cp oss://bucket1/myphoto.jpg  /dir  --checkpoint-dir checkpoint
```

Why are multiple requests logged when downloading a single object?

Two behaviors account for the extra log entries:

Automatic retries: ossutil retries failed or exceptional requests automatically, up to 10 times by default.
Range requests: For objects larger than 100 MB, ossutil downloads the object in parts using range requests. Each part generates a separate log entry.

What should I do if a large object download is interrupted?

Common causes of download interruptions:
- Timeout or disconnect due to a long download.
  
  Network bandwidth limits or unstable connections are the most common causes.
- An end-of-file (EOF) error mid-transfer.
  
  This typically results from a dropped connection or disk read/write speed that cannot keep up with the download rate.
Solution: Use resumable download.
- Specify a checkpoint directory using the --checkpoint-dir option. If the transfer is interrupted, ossutil resumes from where it left off using the saved checkpoint data.
```
./ossutil64 cp examplefile.txt oss://examplebucket/desfolder/ --checkpoint-dir localfolder/
```
- For more information about --checkpoint-dir, see Command syntax.

Why do I get the Error: accessKeyID and ecsUrl are both empty error?

ossutil could not find a configuration file in your home directory.

To resolve this, use either of the following approaches:

Create a configuration file in your home directory before running ossutil commands. For more information, see Install ossutil.

Pass the path to your configuration file explicitly with each command using the -c option:

./ossutil64 cp examplefile.txt oss://examplebucket/destfolder/ -c /home/admin/.ossutilconfig

Why is charset=utf-8 added to the Content-Type of uploaded objects?

ossutil determines an object's Content-Type by looking up the Multipurpose Internet Mail Extensions (MIME) type for the file extension using Go's standard MIME library. This library automatically appends charset=utf-8 to text-based MIME types. For example, an .htm file gets a Content-Type of text/html; charset=utf-8.

Upgrade ossutil to V1.7.14 or later to fix this. Upgrade by reinstalling. For more information, see Install ossutil.

Can I use ossutil to query the size of a directory?

Yes, run the du command. It calls the ListObjects API to retrieve all objects under the specified prefix and calculates the total size. For directories with a large number of objects, the operation may take some 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 (generate a signed URL).

Can I sort the results when listing objects with ossutil?

No, ossutil does not support sorting results when listing objects.

Why do I get a 'no such host' error when running ossutil commands?

The endpoint is invalid. Specify a valid endpoint using the -e option, or update the endpoint in your configuration file. The -e option takes the endpoint for the bucket's region, for example -e oss-cn-shanghai.aliyuncs.com. Do not include 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. Without --all-versions, it calls ListObjects. With --all-versions, it calls ListObjectVersions. In both cases, it also calls ListMultipartUploads. For more information, see API operation calling fees.

Note

If the bucket contains parts from incomplete multipart uploads, fees for ListUploadedParts requests will also apply.