- • Quickstart
- • Documentation
- • Documentation DevOps
- • Next Steps
- • Spring Boot
- • Spring Data
- • Spring Data MongoDB
- • Spring Security
- › Frontend
- • Multi-Module
Last updated: 2023-11-15
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.
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
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.