Part of the Series:
Common WordPress Errors
This tutorial series explains how to troubleshoot and fix common errors that you may encounter when deploying, maintaining, and updating your WordPress installation.
Each tutorial in this series includes descriptions of common deployment, maintenance, or update errors, and explores ways to fix and optimize your installation to scale.
When uploading new media files to your WordPress installation, you may sometimes encounter an issue that can prevent you from writing data to your site’s storage folders. This error typically happens when trying to upload images, videos, and other files to posts and pages on your WordPress site.
In this tutorial, we’ll work to troubleshoot one common error message:
the uploaded file could not be moved to…
This error is a result of failure while attempting to upload a file to your
Step 1 — Identifying and Replicating the Issue
The first step in troubleshooting any issue is to attempt to gain an understanding of where the error is coming from, and how to replicate the issue. If you can isolate an issue to a certain part of your WordPress site’s code, you can better identify how to fix the issue.
Let’s take a look at the error message:
The uploaded file could not be moved to...
From this message, we can identify that although the file was sent to the server, it was not possible to move it to the destination folder
wp-content/uploads or similar. It is likely that the system user running the application doesn’t have permission to write content to the destination folder.
WordPress files are typically hosted on a web hosting server or Droplet, and require certain permissions to work properly. If file permissions are wrong for the file or directory you’re attempting to read or write to, you may receive the error previously mentioned, or a similar error message.
To replicate the issue, attempt to upload (or write) a new file to your intended folder. Notice the behaviors that occur up until the error, and note if the error has changed or remained the same.
If you’ve replicated the issue, move forward to step 2 to fix the permissions issue that is preventing you from uploading to the
wp-content/uploads folder or similar.
Step 2 — Fixing Permissions in WordPress Uploads Folder
For issues with uploading to your
wp-content/uploads folder, you may again be encountering the following error messages:
‘The uploaded file could not be moved to wp-content/uploads/’ ‘Unable to create directory wp-content/uploads/~. Is its parent directory writable by the server?’
To fix this error, you’ll need terminal access to the server where your WordPress site is installed. For more information on how to log into remote servers, you can follow our guide on how to connect to Droplets with SSH, which covers this process in detail. For help with command line basics using Linux, visit A Linux Command Line Primer.
Once you’re logged in, verify the location of your WordPress site on the server. Depending on your setup, this could be a path such as
/usr/share/html/, or a custom location defined by the server administrator. You’ll need this information to execute the next command.
Next, run the following command, which will set up the user
www-data as owner of the WordPress uploads folder. The
www-data user is typically the system user that runs the web server, both on Apache and Nginx installations. This user needs write access to the WordPress uploads folder in order to copy the uploaded file to the correct location.
Replace the highlighted path with the path to your WordPress installation:
- sudo chown -R www-data /var/www/mysite/wp-content/uploads
This command evokes administrator privileges via
sudo, so you may be required to provide your user’s password if this is the first time using
sudo in your terminal session. This will set up correct folder permissions so that the
www-data user is able to read and write data to your
wp-content directory and upload folder.
Step 3 — Testing for Errors
After entering the aforementioned command, it’s time to test for the initial error. Try uploading a new file to your WordPress installation, and note what happens. If you’ve successfully uploaded a file, the permissions have now been set to allow you write access to the intended folder, and the issue should have been resolved.
If you’re still receiving the error message, check with your hosting provider to understand where permissions for your WordPress installation are set, and ask for assistance in setting the correct permissions.
You can find more information about recommended WordPress folder permissions on the official documentation.
In this tutorial, we successfully identified, corrected, and tested an issue in uploading files to the
wp-content folder in a WordPress installation.
For more on WordPress, including help with optimization, installations, and more, visit our comprehensive list of WordPress resources.