Table of Contents

Error Handling

Learn about error handling in the Micronaut framework.

Authors: Sergio del Amo

Micronaut Version: 4.6.3

1. Getting Started

In this guide, we will create a Micronaut application written in Kotlin.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide --build=gradle --lang=kotlin
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Global @Error

We want to display a custom Not Found page when the user attempts to access a URI that has no defined routes.

notfound

The views module provides support for view rendering on the server side and does so by rendering views on the I/O thread pool in order to avoid blocking the Netty event loop.

To use the view rendering features described in this section, add the following dependency on your classpath. Add the following dependency to your build file:

build.gradle
implementation("io.micronaut.views:micronaut-views-velocity")

The Micronaut framework ships out-of-the-box with support for Apache Velocity, Thymeleaf or Handlebars. In this guide, we use Apache Velocity.

Create a notFound.vm view:

src/main/resources/views/notFound.vm
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Not Found</title>
</head>
<body>
<h1>NOT FOUND</h1>

<p><b>The page you were looking for appears to have been moved, deleted or does not exist.</b></p>

<p>This is most likely due to:</p>

<ul>
    <li>An outdated link on another site</li>
    <li>A typo in the address / URL</li>
</ul>
</body>
</html>

Create a NotFoundController:

src/main/kotlin/example/micronaut/NotFoundController.kt
package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Error
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Produces
import io.micronaut.http.hateoas.JsonError
import io.micronaut.http.hateoas.Link
import io.micronaut.views.ViewsRenderer

@Controller("/notfound") (1)
class NotFoundController(private val viewsRenderer: ViewsRenderer<Any, Any>) { (2)

    @Error(status = HttpStatus.NOT_FOUND, global = true) (3)
    fun notFound(request: HttpRequest<Any>): HttpResponse<*> {
        if (request.headers.accept().any { it.name.contains(MediaType.TEXT_HTML) }) { (4)
            return HttpResponse
                .ok(viewsRenderer.render("notFound", emptyMap<Any, Any>(), request))
                .contentType(MediaType.TEXT_HTML)
        }
        val error = JsonError("Page Not Found").link(Link.SELF, Link.of(request.uri))
        return HttpResponse.notFound(error) (5)
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /notfound.
2 Inject an available ViewRenderer bean to render an HTML view.
3 The Error declares which HttpStatus error code to handle (in this case 404). We declare the method as a global error handler due to global = true.
4 If the request Accept HTTP Header contains text/html, we respond an HTML View.
5 By default, we respond JSON.

4.2. Local @Error

Micronaut validation is built on the standard framework – JSR 380, also known as Bean Validation 2.0. Micronaut Validation has built-in support for validation of beans that are annotated with jakarta.validation annotations.

To use Micronaut Validation, you need the following dependencies:

build.gradle
kapt("io.micronaut.validation:micronaut-validation-processor")
implementation("io.micronaut.validation:micronaut-validation")

Alternatively, you can use Micronaut Hibernate Validator, which uses Hibernate Validator; a reference implementation of the validation API.

Then create a view to display a form:

createbook
src/main/resources/views/bookscreate.vm
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Create Book</title>
    <style type="text/css">
        form fieldset li {
            list-style-type: none;
        }
        #errors span { color: red; }
    </style>
</head>
<body>
<h1>Create Book</h1>
<form action="/books/save" method="post">
    <fieldset>
        <ol>
            <li>
                <label for="title">Title</label>
                <input type="text" id="title" name="title" value="$title"/>
            </li>
            <li>
                <label for="pages">Pages</label>
                <input type="text" id="pages" name="pages" value="$pages"/>
            </li>
            <li>
                <input type="submit" value="Save"/>
            </li>
        </ol>
    </fieldset>
</form>
#if( $errors )
    <ul id="errors">
        #foreach( $error in $errors )
            <li><span>$error</span></li>
        #end
    </ul>
#end
</body>
</html>

To use the serialization features described in this section, add the following dependency to your build file:

build.gradle
implementation("io.micronaut.serde:micronaut-serde-jackson")

Create a controller to map the form submission:

src/main/kotlin/example/micronaut/BookController.kt
package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Error
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Produces
import io.micronaut.views.View
import jakarta.validation.ConstraintViolationException
import jakarta.validation.Valid

@Controller("/books") (1)
open class BookController {

    @View("bookscreate") (2)
    @Get("/create") (3)
    fun create(): Map<String, Any> {
        return createModelWithBlankValues()
    }

    @Consumes(MediaType.APPLICATION_FORM_URLENCODED) (4)
    @Post("/save") (5)
    open fun save(@Valid @Body cmd: CommandBookSave): HttpResponse<Any> { (6)
        return HttpResponse.ok()
    }

    private fun createModelWithBlankValues(): Map<String, Any> {
        return mapOf("title" to "", "pages" to "")
    }

}
1 The class is defined as a controller with the @Controller annotation mapped to the path /books.
2 Use @View annotation to indicate the view name which should be used to render a view for the route.
3 You can specify the HTTP verb that a controller action responds to. To respond to a GET request, use the io.micronaut.http.annotation.Get annotation.
4 @Consumes annotation takes a String[] of supported media types for an incoming request.
5 The @Post annotation maps the index method to all requests that use an HTTP POST
6 Add @Valid to any method parameter which requires validation. We use a POJO to encapsulate the form submission.

Create the POJO encapsulating the submission:

src/main/kotlin/example/micronaut/CommandBookSave.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.Positive

@Serdeable (1)
data class CommandBookSave(
    @field:NotBlank val title: String, (2)
    @field:Positive val pages: Int (3)
)
1 Declare the @Serdeable annotation at the type level in your source code to allow the type to be serialized or deserialized.
2 title is required and must be not blank.
3 pages must be greater than 0.

When the form submission fails, we want to display the errors in the UI as the next image illustrates:

createbookserrors

An easy way to achieve it is to capture the javax.validation.ConstraintViolationException exception in a local @Error handler. Modify BookController.java:

src/main/kotlin/example/micronaut/BookController.kt
...
class BookController {
...
..
    private var messageSource: MessageSource
    constructor(messageSource: MessageSource) { (1)
        this.messageSource = messageSource
    }
...
.
    @View("bookscreate")
    @Error(exception = ConstraintViolationException::class) (2)
    fun onSaveFailed(request: HttpRequest<Any>, ex: ConstraintViolationException): Map<String, Any> { (3)
        val model: MutableMap<String, Any> = mutableMapOf("errors" to messageSource.violationsMessages(ex.constraintViolations))
        val cmd = request.getBody(CommandBookSave::class.java)
        cmd.ifPresentOrElse({ model.putAll(mapOf(
            "title" to it.title, "pages" to it.pages
        )) }, {
            model.putAll(createModelWithBlankValues())
        })
        return model
    }

    private fun createModelWithBlankValues(): Map<String, Any> {
        return mapOf("title" to "", "pages" to "")
    }
..
...
}
1 Constructor injection
2 You can specify an exception to be handled locally with the @Error annotation.
3 You can access the original HttpRequest which triggered the exception.

Create a jakarta.inject.Singleton to encapsulate the generation of a list of messages from a Set of ConstraintViolation:

src/main/kotlin/example/micronaut/MessageSource.kt
package example.micronaut

import jakarta.inject.Singleton
import jakarta.validation.ConstraintViolation

@Singleton
class MessageSource {

    fun violationsMessages(violations: Set<ConstraintViolation<*>>): List<String> {
        return violations.map { violationMessage(it) }.toList()
    }

    private fun violationMessage(violation: ConstraintViolation<*>): String {
        val lastNode = violation.propertyPath.map { it.name + " " }.lastOrNull()
        return (lastNode ?: "") + violation.message
    }
}

5. ExceptionHandler

Another mechanism to handle global exception is to use a ExceptionHandler.

Modify the controller and add a method to throw an exception:

src/main/kotlin/example/micronaut/BookController.kt
@Controller("/books") (1)
open class BookController {
...
..
.
    @Produces(MediaType.TEXT_PLAIN)
    @Get("/stock/{isbn}")
    fun stock(isbn: String): Int {
        throw OutOfStockException()
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /books.
src/main/kotlin/example/micronaut/OutOfStockException.kt
package example.micronaut

class OutOfStockException: RuntimeException()

Implement a ExceptionHandler; a generic hook for handling exceptions that occurs during the execution of an HTTP request.

src/main/kotlin/example/micronaut/OutOfStockExceptionHandler.kt
package example.micronaut

import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Produces
import io.micronaut.http.server.exceptions.ExceptionHandler
import jakarta.inject.Singleton

@Produces
@Singleton (1)
@Requires(classes = [OutOfStockException::class, ExceptionHandler::class]) (2)
class OutOfStockExceptionHandler : ExceptionHandler<OutOfStockException, HttpResponse<Any>> { (3)
    override fun handle(request: HttpRequest<*>?, exception: OutOfStockException?): HttpResponse<Any> {
        return HttpResponse.ok(0) (4)
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 This bean loads if OutOfStockException, ExceptionHandler are available.
3 Specify the Throwable to handle.
4 Return 200 OK with a body of 0; no stock.

6. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

6.1. GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 21
sdk install java 21.0.5-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 21
sdk install java 21.0.2-graalce

6.2. Native Executable Generation

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle
graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') (1)
            buildArgs.add('-Ob') (2)
        }
    }
}
1 The native executable name will now be mn-graalvm-application
2 It is possible to pass extra build arguments to native-image. For example, -Ob enables the quick build mode.

After you run the native executable, execute a curl request:

curl -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' localhost:8080/foo

You should get successful response.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Not Found</title>
</head>
<body>
<h1>NOT FOUND</h1>
....

7. Next Steps

Explore more features with Micronaut Guides.

8. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

9. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).