Cloud Platform

Correcting broken file uploads

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:

To modify the settings for the current Drupal version:

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


  • This change affects all uploads and slightly slows down uploads in certain circumstances.

  • 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 path of temporary files, 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 might face issues with temporary files.

  • Acquia recommends that you set your temporary files directory to /mnt/tmp/[sitename].[env]. For more information, see Temporary files. If you face file upload issues, you can update the temporary files directory to /mnt/gfs/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/tmp.

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 the current Drupal version through the core media entity.

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

Support chunked uploads


For Cloud Next applications, Acquia recommends that you use chunked uploads for large files greater than 256 MB.

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:


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 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.


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.