Media Upload Request Flow in WordPress 5.3

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 POST request to .../wp-admin/async-upload.php or to the REST API with the media endpoint (.../wp-json/wp/v2/media/).

The block editor uses the REST API to upload, while any uploads outside the block editor (or using the popup Media Modal) use async-upload.php.

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.

WordPress 5.3+

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.

Legacy Uploads

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 admin-ajax.php with form-data containing action: media-create-image-subsizes and attachment_id: #### to attempt to complete the action.

If all retry attempts fail, the last request to admin-ajax.php has _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 .../wp-json/wp/v2/media/####?force=true&_locale=user with X-HTTP-Method-Override: DELETE header. 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!

#5-3, #dev-notes, #media