Object Storage Service:How to configure browser preview behavior for OSS objects?

Scenario 1: Forced download due to an OSS security policy

This scenario occurs when the response header contains x-oss-force-download: true.

• Cause: OSS adds x-oss-force-download: true and Content-Disposition: attachment headers to prevent certain file types (such as HTML) from executing in browsers. This policy applies when you access objects through an OSS default domain name or an acceleration endpoint in buckets created after a specific date.

  For more information about the policies, see Appendix: Quick reference for OSS forced download rules at the end of this topic.

• Solution: Use a custom domain name to access OSS resources

• Procedure:

  1. Map a custom domain: Log on to the OSS console. On the bucket's Domain Names page, map your custom domain name that has an ICP filing.

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

  3. Access the object with the new domain: Access the object through your custom domain URL. The object now previews inline.

Scenario 2: Forced download due to object metadata settings

This scenario occurs when the response header contains Content-Disposition: attachment but not x-oss-force-download.

• Cause: The object's Content-Disposition metadata is set to attachment, which forces the browser to download rather than display the object. If this setting is not cleared after temporary use, all subsequent requests trigger a download.

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

  • Modify via the console

    1. Log on to the OSS console and navigate to the Objects page in the Object Management section of the target bucket.

    2. Find the target object. Click the ┇ icon in the Actions column and select 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.

  • Modify in batches using ossutil

    # Set the Content-Disposition of a specific object to inline.
    ossutil set-meta oss://your-bucket/your-object.pdf Content-Disposition:inline

Scenario 3: Browser fails to preview the object due to an incorrect Content-Type

This scenario occurs when the response header is normal, but the browser still downloads the object.

• Cause: The object's Content-Type (MIME type) is missing or incorrect. For example, a JPG image with Content-Type set to application/octet-stream downloads because the browser cannot identify the file type.

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

  • Modify via the console

    1. Log on to the OSS console and navigate to the Objects page in the Object Management section of the target bucket.

    2. Find the target object. Click the ┇ icon in the Actions column and select Set Object Metadata.

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

    4. Click OK to save the settings.

    Examples of correct Content-Type for common file types:

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

    • Videos: video/mp4

    • PDF documents: application/pdf

    • HTML files: text/html

    • Plain text: text/plain

  • Modify in batches using ossutil

    # Set the Content-Type of a specific object to image/jpeg.
    ossutil set-meta oss://your-bucket/your-object.jpg Content-Type:image/jpeg

Changes to metadata do not take effect: Check the CDN cache

If you use CDN to accelerate access to OSS, metadata changes such as Content-Type or Content-Disposition may not take effect immediately because CDN nodes still serve the cached version.

Solution: Purge the CDN cache for the modified file's URL in the CDN console. Refresh and prefetch resources.

How to force an object to download instead of being previewed?

To always force a download when users access a file, use one of the following methods.

• Method 1 (Recommended): Configure in OSS. Set the file's Content-Disposition metadata to attachment as described in Scenario 2. Best for permanent, per-file settings.

• Method 2: Configure in CDN. Add Content-Disposition: attachment as an outbound response header under Cache in the CDN console. This avoids modifying the source file and supports batch configuration by path or file type.

Browser does not support the file format for preview

Browsers cannot preview certain professional formats such as .psd, .ai, and .sketch. These files download regardless of OSS and CDN configuration.

Solution: Install a browser extension for the format, or use a document preview service such as WebOffice Online Preview.

OSS default domain names

Acceleration endpoints