Improve "Updating failed. You are probably offline." error message to be more specific and actionable

[annezazu]

At varying points, we've all run into the dreaded "Updating failed. You are probably offline." message:

This error message in general isn't quite actionable or clear so I wanted to open an issue to brainstorm how it can be improved and collect some feedback. This is especially relevant when we think about phase 3 and future collaboration. This builds upon prior related issues like #6322 and #4590 where better autosaving was implemented.

[slrslr]

I had this "probably offline" misleading error and in my case it has been caused by the .htaccess file content security policies ("header set" and "header always set"). Web browser developer console (F12 key), Console tab shown that. After removing these lines (or adding # prefix) and reloading the Wordpress page (F5 key) it started working.

[annezazu]

Coming back to this having had it brought up as feedback recently. In chatting with Claude to better understand why this error appears, I got the following. At a high level, it sounds like we need to 1) add more specific error messages and 2) create better messaging depending on those new error messages.

When the Error Appears
The “Updating failed. You are probably offline.” error message appears in WordPress when:

• During post/page updates - When clicking “Update” or “Publish” in the Gutenberg block editor
• During autosave attempts - When WordPress tries to automatically save your work
• When creating new content - When attempting to save drafts or publish new posts/pages

Why the Error Occurs
The error occurs when WordPress REST API cannot communicate with the WordPress database. The block editor relies on the REST API to send and receive requests to the database for all content operations.

Primary Causes:

• Internet Connectivity Issues: The most obvious cause is an actual loss of internet connection aka unstable or intermittent connectivity that drops during the save operation.
• REST API Communication Failures: WordPress uses a method called the ‘REST API’ to send and receive requests to the WordPress database, and when these requests fail, the error appears.
• SSL/HTTPS Configuration Problems: Mixed content issues where the page loads over HTTPS but requests insecure HTTP resources can trigger this error. The solution to this issue is simply fix your SSL settings. Either disable them all or fix them from end-to-end.
• URL Mismatches Check for the WordPress Address (URL) and Site Address (URL) text boxes. In most cases, they should be the same. If these URLs don’t match or are incorrectly configured, the REST API calls fail.
• Plugin Conflicts: Security plugins that block REST API access (like WP Cerber with “Disable REST API” setting), Plugins blocking REST API and thus the update failed, Caching or optimization plugins interfering with API calls.
• Permalink Structure Issues: REST API endpoint issue when permalink structure is missing a final slash can cause the error.
• PHP Memory Limits: If your WordPress site reaches its PHP memory limit during the updating and publishing processes, you may end up with an “update failed” error.
• .htaccess File Problems: Incorrect or outdated .htaccess configurations can block REST API requests
• Server-Side Issues: Firewall rules blocking REST API endpoints, CloudFlare or CDN services unexpectedly blocking API requests, Server timeout during API communication.

Technical Background

The REST API may stop working if you are not connected to the internet or have lost connectivity. However, the error message “You are probably offline” is somewhat misleading because it’s not exactly the most helpful error message, as it offers no clues as to what’s causing it - in most cases, users aren’t actually offline but experiencing one of the other issues mentioned above. The block editor requires constant communication with the server through REST API calls to function properly, unlike the Classic Editor which doesn’t rely on the REST API for basic operations.

[mcsf]

I've been taking a look, and I think the most relevant thing to understand is this:

The message "You are probably offline" is used by Gutenberg's api-fetch when a Window.fetch promise fails and no discernible error could be parsed in the response (which would happen if the server responded with some error, 4xx, 5xx, etc.). This was implemented six years ago, in #17961, which added some logic to detect more classes of errors and defined "You are probably offline" as a fallback message.

The spec for Window.fetch does not reserve a special error for actual network errors. See fetch § Exceptions: almost everything falls under TypeError, and there are all sorts of errors there, like CORS stuff, malformed request data. This void in the spec pushes some people to try to guess that an error is a network error based on the error's message string (which is not in the spec and varies from browser to browser). We don't do that. It's fragile and I don't like guessing, but maybe, as an imperfect heuristic, we could...?

IIRC, most of api-fetch's development happened early on in Gutenberg's history and it could use more love. Our hands are mostly tied due to the error ambiguity, but maybe we could/should use navigator.onLine as an extra signal when handling errors. Some real-world testing is needed to see how reliable that signal is.

Similarly, maybe the editor could react to online and offline events (i.e. when the browser itself gains/loses network access), perhaps disabling save buttons, perhaps instructing Autosave to not attempt remote saves, perhaps gently letting the user know that they can keep writing but won't be able to save, etc.

Lastly, we should probably log fetch errors to the console, exactly so that we can better debug users' problems. For example, we still log rawHandler's data when content is pasted into the editor, after 8 years, and it's been useful over the years. To be clear, browsers themselves already log errors when the network is down or in other unhandled situations, but who knows if edge cases could be uncovered if we explicitly log the error instance that we catch.

---

All that being said, I do vaguely recall that around 2018–2019 we were spotting cases where certain saving pieces got stuck in a bad state. Autosave comes to mind. We should audit the saving elements to sense if they can ever get stuck (stuck in a save that doesn't complete, or stuck in a state that forbids save actions).

[mcsf]

I had this "probably offline" misleading error and in my case it has been caused by the .htaccess file content security policies ("header set" and "header always set"). Web browser developer console (F12 key), Console tab shown that. After removing these lines (or adding # prefix) and reloading the Wordpress page (F5 key) it started working.

@slrslr: Can you describe your overall experience when you ran into this problem? Was the "You are probably offline" the only issue you experienced? Did the rest of the editor load normally, was something visually different?

---

Based on this feedback, something else comes to mind: would we gain from explicitly testing the REST API upon loading the editor?

[tyxla]

I think @jsnajdr might also be interested in taking a look at this one. I have some vague memories that we worked on something related a few years ago.

[jsnajdr]

apiFetch throws this "You are probably offline" error when the fetch() call returns a rejected promise. This rejected promise can contain a very wide variety of errors that can prevent the fetch from getting a valid HTTP response. The fetch() call either gets a valid response from server (with status code 200-599 and headers), or the fetch() call throws an error.

Collapsing all these errors into "You are probably offline" can be misleading because actually being offline is only one of many reasons why the fetch might fail. Unfortunately for us, many of these errors are intentionally ambiguous and don't reveal information. The exception is typically just TypeError: Failed to fetch. The reason for this is that precise errors can be used to infer information about your local machine and local network. And web pages are generally untrusted code, the script that executes the fetch can be malicious.

The full error is availabe either in the browser console, like:

GET https://example.blog/ net::ERR_NAME_NOT_RESOLVED

and sometimes only in the Network devtool panel, like CORS errors.

We could improve the error message in two ways:

1. Display the full error message from fetch() instead of "You are probably offline". Most of the time it will be just "Failed to fetch", but not always, so there is a slight improvement.
2. Tell the user to look at the browser console if they want to know more.

Admittedly this is not a big improvement, but I'm afraid it's all we can do with the existing limitations.

For illustration, here's an overview of possible ways how the fetch can fail:

1. The parameters of the request are wrong. URL cannot be parsed, has unsupported scheme, contains credentials (not allowed), has unsupported method. headers are wrong: not an array of tuples, bad header names. Bad referrer value. A forbidden port value.
2. The request fails security policies like CSP or CORS.
3. The hostname cannot be resolved in DNS.
4. We can't connect to the remote host (the only part where "probably offline" is really true)
5. The TCP connection is reset at any time when sending the request and reading the response.
6. There is a problem with the server TLS certificate (invalid, expired, etc.), any failure to establish a TLS channel.
7. The HTTP response sent by the server is invalid in any way.
8. The HTTP response is rejected by CORS policy.

@slrslr commented about .htaccess config causing errors when header set or header always set directives are used. I don't know how this could possibly cause fetch errors. Maybe the headers in question were CORS headers (Access-Control-Allow-*) that made the CORS check fail?

[tyxla]

To add on to what y'all are already considering and discussing, I understand that one of the primary points of confusion is the "You are probably offline" part.

I believe it's pretty easy to verify if the user is online or not by using window.navigator.onLine. I remember playing with that earlier as I was tinkering with early offline mode improvements in #59025. If folks find that compelling, I'd be happy to revive that PR and then we could use the useNetworkConnectivity() hook there to determine whether we're online or not in realtime.

Using that, would be able to effectively remove the ambiguity, and say "You are offline" if they're offline, and use a generic message if they're online and something else happened.

What do y'all think?

[jsnajdr]

Yes, navigator.onLine is a useful one additional bit of information when figuring out the error. We don't even need to observe it in real-time, just read it when an error actually occurs. Then we can divide the fetch errors into three classes:

1. You are offline. Not probably, but for sure.
2. An explicit informative error when the fetch fails. These will be rare, the fetch request must be somehow malformed to trigger such error.
3. A generic "failed to fetch" network error that happened despite being online. We don't know any details about this error, the best we can do is to advise the user to consult developer tools.

[tyxla]

Yep, agreed, not really needed in real time if this is about handling apiFetch() requests.

What makes me a bit reluctant about this change is that this is about changing the error behavior of the default handler of apiFetch(), which will have an impact on most of the requests performed in Gutenberg. On the positive side, it might at least be helpful to differentiate between "failed because offline" and "you're online, and it failed for another reason".

Translating the classes you listed into actual error messages the user will see, we might have something like:

• 1: "You are currently offline."
• 2: The actual informative error, as it was thrown
• 3: "An unexpected error occurred." or any other generic error message.

Revisiting what I said earlier, I think there's not much from #59025 we can reuse, considering this is in the apiFetch handler and not in reactive code.

[mcsf]

"failed to fetch"

Please be mindful of the fact that this string is browser-dependent. I originally mentioned this in #67141 (comment), so you're probably aware, but it wasn't clear in the responses — so I thought I'd double-check.

With that in mind, I think the three-way classification of failures is a good start.

One thing that concerns me is that the notices aren't reactive. So, while I agree that the first and most important step is to capture the value of navigator.onLine at the time of the error, we run the risk of making things even more confusing for some users. These users would now be shown a notice that adamantly says "You are offline" but never updates even after users fix their network connection. So I suggest finding small tweaks in the wording that could mitigate this.

That said, perfect is the enemy of good, and I don't want my hesitations to slow us down here.

[jsnajdr]

Please be mindful of the fact that this string is browser-dependent.

Yes this is true, thanks for linking to the is-network-error code that enumerates the error string constant for various browsers, even older ones. In any case, it's a predefined constant that can be detected.

These users would now be shown a notice that adamantly says "You are offline" but never updates even after users fix their network connection. So I suggest finding small tweaks in the wording that could mitigate this.

We can say the offline thing in past tense:

Updating failed because you were offline.

We no longer need to say "probably" and using past tense in both parts of the sentence is probably a better English grammar anyway 🙂

notice that adamantly says "You are offline" but never updates even after users fix their network connection.

We could implement some retry logic, at least for read-only GET requests. But retrying POST requests is dangerous, especially for network errors: a network error, especially when reading the HTTP response from server, doesn't mean that the POST operation wasn't performed! The database write or whatever can be already done at this moment. There is a risk of writing/creating something twice.

Another improvement could be a network state indicator somewhere in the editor toolbar. There is already prior art on all this in Calypso. Network state UI, refetch login in data-layer... Nothing new under the sun.

[mcsf]

Agreed with everything, and the phrasing "Updating failed because you were offline." seems like a great improvement.

[tyxla]

Sounds like we have a clear path for improving the current confusing state. @mcsf or @jsnajdr, is any of you planning to open a PR?