New Download Handling May Cause Errors


Recent updates that improve security around the handling of downloadable products may cause unexpected errors in some environments.

The details

WooCommerce currently supports three different download methods for downloadable products:

  • Force Downloads
  • X-Accel-Redirect/X-Sendfile
  • Redirect Only (Insecure)

Each of these methods can fail for a number of different reasons. Up until recently, WooCommerce attempted to handle these failures via a system of fallbacks, whereby:

  • If the file cannot be served by X-Accel, fallback on Force Download.
  • If the file cannot be served by Force Download, and if the file is ‘remote’, fallback on Redirect.
  • If the file cannot be served by Redirect, display an error message.

Note that the Redirect method is considered insecure because it exposes the URLs for downloadable products in an obvious way, which makes it possible for someone to access the download without having purchased the product.

As of WooCommerce 5.5.0, the fallback to the Redirect method was removed, however the method itself is still an option for merchants who want to explicitly select it. The removal of this fallback may result in merchants and customers encountering errors when trying to access downloadable products in stores that are configured to serve those downloads via the Force Download or X-Accel-Redirect/X-Sendfile methods but which are, for various reasons, unable to serve them successfully.

How can I tell if this affects me?

Stores who could potentially encounter errors due to this new behavior will meet the following criteria:

  • Your store is running WooCommerce 5.5 or 5.5.1.
  • You sell downloadable products.
  • You use the Force Downloads or X-Accel-Redirect/X-Sendfile method to serve downloadable products.

Given this setup, if the server is unable to serve downloads via the method you have chosen, customers may encounter the errors mentioned above.

What action should I take?

As always, we recommend stores run the latest release of WooCommerce. WooCommerce 5.5.2 was recently released, and it contains improvements that allow stores to explicitly fall back on the Redirect method as a last resort.

If you are encountering errors, we recommend you take the following steps:

  • Update to WooCommerce 5.5.2 and select the option to allow using redirect mode as a last resort. This means that your preferred method, such as Force Download, will always be used if possible but if for any reason it cannot be used—and only in those cases—redirects will be used instead.
  • Work with your hosting provider to ensure that your store’s server environment is configured properly for serving files via one of the other two methods. WooCommerce 5.5.2 includes additional logging that helps merchants and site administrators see when fallbacks are being triggered so they can take corrective action. If you need additional guidance, you can find instructions in the documentation for Digital/Downloadable Product Handling.

We are looking for other opportunities to make the downloadable product experience more reliable and efficient, so we eager to hear more about how you use downloadable products in your store. Leave us a note in the comments below or reach out to us in the WooCommerce Community Slack.

One response to “New Download Handling May Cause Errors”

  1. […] New improvements to the security around download handling may produce errors in some environments. You can learn more in a recent developer advisory about the changes. […]

Leave a Reply

Your email address will not be published. Required fields are marked *