Information for: DEVELOPERS   PARTNERS   SUPPORT

Correcting broken file uploads

Important

EOL notice! Drupal 8 reached end-of-life on November 2, 2021. For more information, see Frequently Asked Questions.

The Cloud Platform Enterprise platform uses two or more load balancing nodes to handle incoming requests, routing them to available application-layer infrastructure in a way that shares the load across multiple nodes. Cloud Platform Enterprise users may experience problems with file uploads on multi-node configurations. When Drupal temporarily uploads a file to a path that is not accessible by another web node that needs to access it, unexpected behavior may occur.

If this happens, Acquia recommends you to set the temporary files directory.

Another common cause for uploads to fail is very large file uploads. In this scenario, Acquia always recommends the use of a chunked upload module, which splits your large file into many chunks. If it is misconfigured, chunks scatter across multiple web nodes, making it impossible to ‘stitch’ the upload back together.

For large file uploads, use a contributed module for file uploads.

Setting the temporary files directory in settings.php

You can permanently set your website’s temporary files directory by adding a setting to the website’s settings.php file after the Acquia include statement. The setting for you to use varies, depending on your Drupal version:

For Drupal 7:

$conf['file_temporary_path'] = "/mnt/gfs/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/tmp";

For Drupal 8 or later:

$settings['file_temp_path'] = "/mnt/gfs/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/tmp";

Note

  • This change affects all uploads and slightly slows down uploads in certain circumstances where it is not desired.
  • The temporary paths referenced in these methods must be manually created before use. Setting variables does not create the folders, and causes uploads to fail until you create the directory.
  • If you cannot locate the temporary files path, you can set a custom directory to store them. You must create the custom directory on the shared file system. You must also ensure that the file path you provide to the file_temp_path parameter already exists. Otherwise, you may face issues with temporary files.

Use contributed modules for file upload handling

Contributed modules can be configured to help work around these issues on a permanent basis, which work by first creating a temporary file for each uploaded file. After the temporary file is on the infrastructure, the file is then moved to its final destination. For applications running on single-node Cloud Classic infrastructure, such as Cloud Platform Professional applications, this works without any errors. For applications running on Acquia Cloud Enterprise, however, you may experience errors when some of the uploaded files don’t save properly.

Files added by these modules to Cloud Platform Enterprise applications are saved to a temporary location that is not shared between the redundant provisioned infrastructure. It is possible for the move process to take place on a node that is different from the one that the file is uploaded to, which causes that move to fail and the upload to appear broken.

Acquia does not recommend a specific module because it often depends on the configuration of your Drupal site. Commonly-used modules include:

Dropzone provides an open source javascript library to handle drag and drop file uploads with image previews, and supports chunked uploads. The Drupal module integrates it seamlessly into Drupal 8 or later via the core media entity introduced since Drupal 8.4.

Currently, a patch is required to enable chunked uploading, which is best installed through Composer:

https://www.drupal.org/project/dropzonejs/issues/3125682

Plupload is a popular plugin to enhance the file upload experience on a website. Plupload is also a popular choice for Drupal-based websites. To add the plupload library functionality to Drupal, you must install and enable the Plupload integration module.
The Webform module can show multi-node upload issues in certain cases.
The Editor File upload module is compatible with Drupal 8 or later and CKEditor. It creates a button in the toolbar to link and upload data as part of content creation, rather than manually linking a file.
The Alternative Stream Wrappers module for Drupal allows Drupal to continue to use the built-in stream wrappers (such as public:// and temporary://), but also use one or more alternative stream wrappers – for cases including the shared temporary directory.

For all appropriate modules, ensure that you configure the temporary files directory.

Alternative solutions

You can temporarily force all of your upload requests to the same node. To do this, Acquia recommends you to use one of the following methods:

Important

These alternatives are for temporary use only and should be removed when you are not uploading critical files. It will not work on environments running on Acquia Cloud Next technologies. Overuse of these methods causes performance problems for your application. In a shared environment, it also causes problems for other customers on the infrastructure.

Note

In the past, Acquia recommended using the Sticky Sessions module on Acquia Cloud Platform. Acquia does not recommend you to use this module anymore. For more information, see Modules to use with caution on Cloud Platform.