cacheControl: 'no-cache' Not Working in downloadData (AWS Amplify Gen 2)

[EmilioSantos-gif]

Environment information

❯ npx ampx info
System:
  OS: Linux 5.15 Ubuntu 20.04.6 LTS (Focal Fossa)
  CPU: (12) x64 Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz
  Memory: 3.90 GB / 15.46 GB
  Shell: /usr/bin/zsh
Binaries:
  Node: 23.6.1 - ~/.nvm/versions/node/v23.6.1/bin/node
  Yarn: 1.22.19 - /usr/local/bin/yarn
  npm: 11.1.0 - ~/.nvm/versions/node/v23.6.1/bin/npm
  pnpm: undefined - undefined
NPM Packages:
  @aws-amplify/auth-construct: 1.3.1
  @aws-amplify/backend: 1.5.0
  @aws-amplify/backend-auth: 1.2.0
  @aws-amplify/backend-cli: 1.2.9
  @aws-amplify/backend-data: 1.1.4
  @aws-amplify/backend-deployer: 1.1.5
  @aws-amplify/backend-function: 1.7.0
  @aws-amplify/backend-output-schemas: 1.3.0
  @aws-amplify/backend-output-storage: 1.1.2
  @aws-amplify/backend-secret: 1.1.4
  @aws-amplify/backend-storage: 1.2.1
  @aws-amplify/cli-core: 1.1.3
  @aws-amplify/client-config: 1.4.0
  @aws-amplify/deployed-backend-client: 1.4.2
  @aws-amplify/form-generator: 1.0.3
  @aws-amplify/model-generator: 1.0.8
  @aws-amplify/platform-core: 1.1.0
  @aws-amplify/plugin-types: 1.3.0
  @aws-amplify/sandbox: 1.2.3
  @aws-amplify/schema-generator: 1.2.4
  aws-amplify: 6.12.3
  aws-cdk: 2.163.1
  aws-cdk-lib: 2.163.1
  typescript: 5.6.3
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!                                                                                                                      !!
!!  This software has not been tested with node v23.6.1.                                                                !!
!!  Should you encounter odd runtime issues, please try using one of the supported release before filing a bug report.  !!
!!                                                                                                                      !!
!!  This software is currently running on node v23.6.1.                                                                 !!
!!  As of the current release of this software, supported node releases are:                                            !!
!!  - ^22.0.0 (Planned end-of-life: 2027-04-30)                                                                         !!
!!  - ^20.0.0 (Planned end-of-life: 2026-04-30)                                                                         !!
!!  - ^18.0.0 (Planned end-of-life: 2025-04-30)                                                                         !!
!!                                                                                                                      !!
!!  This warning can be silenced by setting the JSII_SILENCE_WARNING_UNTESTED_NODE_VERSION environment variable.        !!
!!                                                                                                                      !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
AWS environment variables:
  AWS_STS_REGIONAL_ENDPOINTS = regional
  AWS_NODEJS_CONNECTION_REUSE_ENABLED = 1
  AWS_SDK_LOAD_CONFIG = 1
No CDK environment variables

Describe the bug

Summary
When using downloadData from @aws-amplify/storage, passing cacheControl: 'no-cache' does not prevent caching. Despite being removed in Amplify v6, the AWS Amplify Gen 2 documentation explicitly states that cacheControl: 'no-cache' should work to fetch the latest version of a file.

Expected Behavior
Passing { cacheControl: 'no-cache' } should force fetching the latest version of the file, as described in the Amplify Gen 2 documentation.

Reproduction steps

1. Use downloadData from @aws-amplify/storage to download a file from S3.
2. Modify the file in S3.
3. Call downloadData again with { cacheControl: 'no-cache' } to attempt to fetch the latest version.
4. Observe that the previous cached version is returned instead of the latest file.

[ykethan]

Hey,👋 thanks for raising this! I'm going to transfer this over to our JS repo for better assistance.

[joon-won]

Hey @EmilioSantos-gif can you provide us code snippet to reproduce the issue? Meanwhile, we have realized a part of our documentation is outdated as the option has been removed when v6 was introduced.

[EmilioSantos-gif]

Hey @EmilioSantos-gif can you provide us code snippet to reproduce the issue? Meanwhile, we have realized a part of our documentation is outdated as the option has been removed when v6 was introduced.

I tried with:

downloadData({ path: "path-to-file", cacheControl: "no-cache" })

But also:

downloadData({ path: "path-to-file", options: { cacheControl: "no-cache" } })

[HuiSF]

Hi @EmilioSantos-gif, by default, in Amplify JS v6, the downloadData API doesn’t enforce any cache behavior because it relies on the runtime. Consequently, cacheControl isn’t a valid option parameter in Amplify JS v6 (the documentation you linked above contains inaccurate information; we’re working on fixing it).

To clarify, do you want to control the cache behavior for each downloadData API call?

An available alternative is to use getUrl to generate a presigned URL for downloading, every newly generated URL forces to ignore caching.

[EmilioSantos-gif]

Hi @EmilioSantos-gif, by default, in Amplify JS v6, the downloadData API doesn’t enforce any cache behavior because it relies on the runtime. Consequently, cacheControl isn’t a valid option parameter in Amplify JS v6 (the documentation you linked above contains inaccurate information; we’re working on fixing it).

To clarify, do you want to control the cache behavior for each downloadData API call?

An available alternative is to use getUrl to generate a presigned URL for downloading, every newly generated URL forces to ignore caching.

I think the issue is resolved now since you clarified that the documentation is inaccurate. The reason I posted this issue was that the documentation stated that cacheControl should work in Amplify Gen 2, which led me to believe I could use it to manage caching.

Thanks for providing the workaround with getUrl—I’ll try that approach to ensure I always retrieve the latest version of the file.

I appreciate your help!

[HuiSF]

Hi @EmilioSantos-gif We appreciate that you’re following up and helping us consistently improve Amplify! Thanks!

Before I close the issue, I still want to clarify, for your use cases, would you prefer to have a cache control option for the downloadData API?