Object Storage Service:Configure object preview behavior in OSS

Scenario 1: Download forced by security policy

This scenario applies when the response header includes x-oss-force-download: true.

• Cause: To prevent potential security risks from specific types of files, such as HTML, being executed directly in a browser, OSS forces a file download by adding the x-oss-force-download: true and Content-Disposition: attachment response headers. This behavior applies to some file types in some regions when you use an OSS default domain name or a transfer acceleration domain name to access a bucket created after a specific point in time.

  For details about the policy, see Appendix: OSS forced download rules.

• Solution: Access OSS resources by using a custom domain name.

• Procedure:

  1. Bind a custom domain name to the bucket: Log on to the OSS console. On the Domain Names page for the target bucket, bind a custom domain name that has a valid ICP filing to the bucket.

  2. Configure a CNAME record: Go to your DNS provider, such as Alibaba Cloud DNS, and add a CNAME record that maps your custom domain name to the CNAME address provided by OSS.

  3. Access the object by using the new domain name: After you complete the configuration, use the custom domain name URL to access the object. It will then be previewed in the browser.

Scenario 2: Download forced by object metadata

This scenario applies when the response header includes Content-Disposition: attachment but not the x-oss-force-download field.

• Cause: The Content-Disposition field in the object's metadata is explicitly set to attachment. This setting instructs the browser to download the object as an attachment instead of displaying it inline. This setting is often used to generate temporary download links. If not removed, it causes all subsequent access attempts to trigger a download.

• Solution: Change the object's Content-Disposition metadata to inline.

  • Modify in the console

    1. Log on to the OSS console, and navigate to the Objects > object list page for the target bucket.

    2. Find the target object. In the Actions column, choose ┇ > Set Object Metadata.

    3. In the dialog box that appears, find the Content-Disposition field and change its value to inline.

    4. Click OK to save the settings.

  • Use ossutil for batch updates

    # Set the Content-Disposition of a specified object to inline.
    ossutil set-props oss://your-bucket/your-object.pdf --content-disposition inline --metadata-directive update

Scenario 3: Incorrect Content-Type prevents preview

In this scenario, the HTTP response header is normal, but the browser still downloads the object.

• Cause: The Content-Type (also known as MIME type) in the object's metadata is incorrect or missing. For example, if a JPG image has a Content-Type of application/octet-stream, the browser downloads the object because it does not recognize the content type.

• Solution: Set the correct Content-Type for the object.

  • Modify in the console

    1. Log on to the OSS console, and navigate to the Objects > object list page for the target bucket.

    2. Find the target object. In the Actions column, choose ┇ > Set Object Metadata.

    3. In the dialog box that appears, find the Content-Type field and change its value to the correct one.

    4. Click OK to save the settings.

    Examples of correct Content-Type values for common object types:

    • Images: image/jpeg, image/png, image/gif, image/webp

    • Video: video/mp4

    • PDF documents: application/pdf

    • HTML files: text/html

    • Plain text: text/plain

  • Use ossutil for batch updates

    # Set the Content-Type of a specified object to image/jpeg.
    ossutil set-props oss://your-bucket/your-object.jpg --content-type image/jpeg --metadata-directive update

Metadata changes not effective: Check CDN cache

If you use Content Delivery Network (CDN) to accelerate access to OSS, changes to object metadata, such as Content-Type or Content-Disposition, may not take effect immediately because CDN nodes are still serving cached content with the old headers.

Solution: Log on to the CDN console and purge the URLs for the modified objects to clear the CDN cache. For detailed instructions, see Purge and prefetch resources.

Force an object to download

To force an object to download instead of being previewed, use one of the following methods.

• Method 1 (Recommended): Configure on the OSS side. As described in Scenario 2, set the object's Content-Disposition metadata to attachment. This method is ideal for applying a permanent download setting to individual objects.

• Method 2: Configuration on the CDN side. If you use CDN, you can add the Content-Disposition: attachment header in the CDN console by configuring the HTTP response header in Cache Settings. This method does not require you to modify objects in the OSS origin and is suitable for batch and flexible rule configuration for specific paths or file types.

Unsupported format for browser preview

Mainstream browsers do not natively support previews for some specialized object formats, such as .psd, .ai, and .sketch. In these cases, the browser downloads the object even with correct OSS and CDN configurations.

Solution: Install a browser extension or plug-in that supports previewing the specific object format. Alternatively, you can use a professional document preview service, such as WebOffice online preview.

OSS default domain names

Transfer acceleration domain names