Last updated: 2023-11-15

  1. Learn
  2. Frontend
  3. Htmx Error Handling

Htmx error handling in Spring Boot apps

Htmx is a fantastic library to simplify web application development and render most of the HTML directly in the backend. However when making calls to the server, expected and unexpected errors can occur - how they are handled best in our Spring Boot application?

Let's assume we already have our Spring Boot application with Thymeleaf and htmx prepared - more details here. Let's add an endpoint to the HomeController that throws an exception - in the real world this could occur, for example, if the database is not available.

Adding an endpoint producing an "unexpected" error

The Thymeleaf template resources/templates/error.html is added to the repository, which will be picked up and rendered by Spring Boot when an Exception occurs.

Our very simple error template

If we now call our endpoint directly via http://localhost:8080/fail in the browser, the user sees our prepared template - as it should be. The situation however is different if the page is loaded by htmx via an AJAX request. This could happen for example if the hx-boost="true" flag is set on the body tag in the page http://localhost:8080/ - in this case, the user would receive no feedback at all in the browser when clicking on the link.

There are two issues we need to address here:

  • because AJAX requests are sent with the header Accept: */*, the regular error handling of Spring Boot returns a JSON response
  • the response has the HTTP status 500, so htmx does not perform swapping in the browser

We can solve these points either in the backend or client part of our application.

Adding a dedicated error handling to our app

In order to display the error page in the browser for htmx requests as well, we can add the following controller to our application.

Special controller for error output of htmx requests

With this we have a new endpoint on the configured error path that outputs regular HTML with HTTP status 200. By specifying the header HX-Request=true it becomes exclusively active for requests by htmx. Since the result is rendered directly via BasicErrorController, we get exactly the same result as on regular error pages.

Error handling in the browser

Alternatively, we can handle the error output in the client without adding the controller. Here we could first customize the Accept header for htmx requests, so the regular error handling in our Spring Boot application will be applied.

Adjusting the Accept header for htmx requests

However, the HTTP response status would still be 500 in this case - so htmx will not do the swapping by default (see htmx docs). In order to change this behavior, we need to intercept the htmx:beforeSwap event in our JavaScript code and set the shouldSwap property to true in any case.

Extending our JavaScript code

With the Bootify Builder a Spring Boot application with database schema and Thymeleaf frontend can be generated. An option to include htmx is available in the Free plan - with this the application already has the hx-boost="true" flag set and the HtmxErrorController is integrated.

Learn more
or see pricing