htmx silently ignores 4xx/5xx responses: how should swap errors be announced to screen-reader users?

Direct answer

Place an ARIA live region outside the element targeted by hx-target, give it role='status' and aria-live='polite', and announce errors from the htmx:responseError event. When a swap removes the triggering control, store a reference to the element before the request and, in htmx:afterSwap, move focus to the live region or a persistent summary.

Why this works

By default htmx 1.9.x swaps the response only for status code 422; most 4xx/5xx responses leave the DOM unchanged, so sighted users see no change and screen‑reader users receive no announcement. An aria-live region that survives the swap provides a perceivable signal. The htmx:responseError event fires for every non‑2xx response (including 4xx/5xx) and is the reliable hook for announcing failures; hx-target-error only redirects the error body into the DOM and does not trigger live updates automatically. Focus must be restored manually because htmx does not retain focus after it removes the triggering element.

Implementation steps

1. Add a live region to the page, outside any container that will be swapped:

   <div id='htmx-error-live' role='status' aria-live='polite' aria-atomic='true' style='position:absolute; left:-9999px;'></div>

2. In your script, listen for htmx:responseError and update the live region:

   document.body.addEventListener('htmx:responseError', function(evt) {
     const live = document.getElementById('htmx-error-live');
     // Use the response text or a generic message
     const msg = evt.detail.xhr.responseText || 'Request failed';
     live.textContent = msg;
   });

3. Optionally, also handle htmx:afterSwap to clear the live region after a successful swap:

   document.body.addEventListener('htmx:afterSwap', function(evt) {
     if (!evt.detail.failed) { // successful swap
       const live = document.getElementById('htmx-error-live');
       live.textContent = '';
     }
   });

4. Preserve focus when the triggering element may be removed:

   let triggerEl = null;
   document.body.addEventListener('htmx:beforeRequest', function(evt) {
     triggerEl = evt.detail.target; // the element that initiated the request
   });
   document.body.addEventListener('htmx:afterSwap', function(evt) {
     if (triggerEl && !document.contains(triggerEl)) {
       // element was removed; focus the live region or a fallback
       const live = document.getElementById('htmx-error-live');
       live.focus();
     }
     triggerEl = null;
   });

Verification and missing detail

To confirm that the approach matches your exact htmx build, verify which status codes trigger htmx:responseError in your version. If the failing responses are 422 (which htmx swaps by default), the live region may receive duplicate announcements; in that case you might prefer to rely on the swapped error markup instead. Please confirm whether the error responses you encounter are 422 or other 4xx/5xx codes, as this determines whether the live‑region strategy is needed.