After a couple of questions from hosting companies about how to detect how well uploads are working at the server/request level, I thought further documentation would help.
Here is a walkthrough of the request flow for media uploads, both before and after WordPress 5.3. Hopefully this will help with troubleshooting and debugging uploads on your infrastructure or sites!
Before WordPress 5.3
Before WordPress 5.3, uploads had to complete during a single HTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. POST request to
.../wp-admin/async-upload.php or to the REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. with the media endpoint (
The block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor uses the REST API to upload, while any uploads outside the block editor (or using the popup Media Modal) use
When uploads failed, they would return whatever HTTP error the server is set up to give (usually in the
5xx range). This is usually due to timeout or resource exhaustion (like running out of memory) reasons.
In WordPress 5.3+, uploads have been decoupled from a single request to allow for resuming. Now, when an upload returns a
5xx error, there can be up to 5 followup requests.
This is accomplished differently depending on whether
async-upload.php or the REST API are used.
Outside of the REST API, the upload happens first with a request to
async-upload.php, just like before 5.3.
If it fails, a request is made to
action: media-create-image-subsizes and
attachment_id: #### to attempt to complete the action.
If all retry attempts fail, the last request to
_wp_upload_failed_cleanup: true in
form-data and attempts a cleanup. This deletes the the attachment post, the uploaded file, and any intermediate sizes that were created. Then, an error message is shown to users advising them to scale down the image and try uploading again.
REST API Uploads
When using the REST API, the initial request is to
.../wp-json/wp/v2/media?_locale=user, and retry requests are to
.../wp-json/wp/v2/media/####/post-process?_locale=user (where #### is the attachment post ID).
If all attempts to resume post-processing fail with HTTP 5xx errors, the last is a standard “delete attachment” request, sent to
X-HTTP-Method-Override: DELETE header The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. It performs the same cleanup as described for the
admin-ajax.php upload method.
Hopefully this helps in understanding how uploads work! If you have any questions, please ask in the comments for clarification.
Thanks to @azaozz for helping write this post!