Last updated: 2024-04-19

1. Learn
2. ›
3. Frontend
4. ›
5. Htmx Error Handling

Htmx error handling in Spring Boot apps

Did you know that you can save days or weeks of development time when starting new Spring Boot apps? br With Bootify you have the right helper at your side - get a runnable prototype in minutes and focus on your business logic instead. Best practices included.
Discover more

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.

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.

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.

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.

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.

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