Improve wording for error message on failed post-processing of uploads

[eclev91]

Right now if post-processing fails on upload in any way, the error message reads:

"Post-processing of the image failed. If this is a photo or a large image, please scale it down to 2500 pixels and upload it again."

This message is an improvement over the previous one, but the suggestion is arbitrary and comes across as a definitive solution when there could be any number of causes. I think it's worth workshopping this message to avoid a situation in which end users are resizing their images and still getting timeouts ("But I already did that! WordPress is dumb!"). Could also prevent developers trying to debug thinking 2500px is some kind of magic number.

Some thoughts:

• Don't suggest resizing on a 500 error as opposed to a 504 timeout, where resource management is a more likely culprit. "WordPress encountered an error during post-processing of this upload." versus "Post-processing of this upload took too long."
• Make clear this is a suggestion, not a definitive issue. "Uploading a smaller image may help."

I thought I'd get some feedback from UX folks before putting in a patch.

[desrosj]

I do think this message needs to be refined a bit, but I don't have any suggestions at the moment.

There has been a large amount of confusion caused by this error message where users think disabling the "big" image size scale down feature is causing this error message when it is actually being caused by a server error or a failure with post processing.

[azaozz]

I also agree that the message can be better, but not sure exactly how to change it :)

Don't suggest resizing on a 500 error as opposed to a 504 timeout

This is somewhat arbitrary. The server can be configured to send different 5.x.x errors for different failures. Initially retrying of the post-processing happened only on HTTP 500 errors, but that had to be extended to all 5.x.x errors as different servers were configured to return different error codes. Unfortunately trying to "guess" the exact error by the error code doesn't seem possible.

Make clear this is a suggestion, not a definitive issue.

Yeah, lets do this. Perhaps something like:

Post-processing of the image failed. Uploading a smaller image may help. If this is a large image, please scale it down to 2500 pixels and try to upload it again.

Or perhaps:

Post-processing of the image failed, likely because the server is busy or does not have enough resources. Uploading a smaller image may help. If this is a large image, please scale it down to 2500 pixels and try to upload it again.

More/better suggestions welcome.

[azaozz]

Another variation:

Post-processing of the image failed likely because the server is busy or does not have enough resources. Uploading a smaller image may help. Suggested maximum size is 2500 pixels.

[desrosj]

Most of the confusion that I have seen comes from having a specific dimension in the message, even if it is just a suggestion. Users are mistaking the -scaled full-size image with a general server error that was previously not reported to the user in the admin and failed silently.

What if we created a page on the help hub explaining common reasons why an image upload may fail with suggestions to debug further or fix them?

For example:

• Too many (tens-hundreds) of image sizes registered on the site (potentially from using lots of plugins, or a poorly built theme). Uploading large images may cause the server to run out of resources and be unable to complete processing all of the sizes.
• Original source is too large. Try optimizing the image or uploading a smaller version.
• etc.

If we chose this route, the message could be something more general like this:

The server was unable complete the post-processing for this upload. *link*Helpful troubleshooting information.*link*

[azaozz]

Replying to desrosj:

What if we created a page on the help hub explaining common reasons why an image upload may fail with suggestions to debug further or fix them?

Think this was discussed a bit. The difficulties there will be with translation. We can make the URL "translatable" so it points to the appropriate help page, but that "pushes" it to the translation teams to confirm translated pages exist for all locales and are up to date.

On the other hand that will give a lot more "space" to outline next steps and general troubleshooting of failures while uploading. See ​https://wordpress.org/support/topic/unable-to-upload-images-67/page/6/#post-12277831 for some initial content.

[desrosj]

Another idea is to let hosting companies filter the link to send users to company specific documentation and troubleshooting information.

Right now, there are too many different reasons this error may be encountered, so it’s just hard to properly summarize and advise in one admin notice.

[antpb]

I really liked @azaozz ’s suggestion of:

“Post-processing of the image failed likely because the server is busy or does not have enough resources. Uploading a smaller image may help. Suggested maximum size is 2500 pixels.”

I’m going to work on getting a patch ready for Beta 1 that includes those text changes. We can iterate on it as the beta cycles go on, but I’d like to get something in ahead of time. Any thoughts @desrosj and @azaozz ?

[azaozz]

Replying to antpb:

Yep, lets do it. I like all the suggestions, the more context and troubleshooting tips - the better :)

Perhaps it can have that text and then a fully translatable and filterable (text and URL) *link*Helpful troubleshooting information.*link* at the end. That will make it fully customizable by hosting companies/plugins. Perhaps something like:

$more_info = '<a href="' . __( 'https://help/link' ) . '">' . __( 'Helpful troubleshooting information.' ) . '</a>';
$more_info = apply_filters( 'wp_image_upload_fatal_error_help_link', $more_info );

[eclev91]

Replying to azaozz:

Since I opened the ticket, I wanted to second support of both that phrasing and the "more info" link.

[davidbaumwald]

This ticket still needs a patch, and with 5.4 Beta 1 landing tomorrow, this is being moved to Future Release. If any maintainer or committer feels this can be included in 5.4 or wishes to assume ownership during a specific cycle, feel free to update the milestone accordingly.

[azaozz]

In 47259:

Media: Improve wording for error message on failed post-processing of uploaded images.

Props eclev91, desrosj, antpb, azaozz.
Fixes #49280.

[azaozz]

Lets look at adding the link to troubleshooting help after it is available. Most likely at: ​https://wordpress.org/support/article/faq-troubleshooting/.