quarkusio/quarkus · error · UnhandledAnnotatedException

unhandled

Error message

unhandled

What it means

voidWithUnhandledAnnotatedException throws UnhandledAnnotatedException, a checked exception annotated in a way that deliberately has NO exception mapper registered in this test app. Without a mapper, Quarkus/RESTEasy Reactive maps it to HTTP 500 and propagates the message 'unhandled' — this endpoint exists to test that unmapped-exception behavior.

Source

Thrown at integration-tests/spring-web/src/main/java/io/quarkus/it/spring/web/ExceptionThrowingController.java:18

package io.quarkus.it.spring.web;

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

@RestController
@RequestMapping("/exception")
public class ExceptionThrowingController {

    @RequestMapping(method = RequestMethod.GET, path = "/unhandled/exception")
    public void voidWithUnhandledAnnotatedException() throws UnhandledAnnotatedException {
        throw new UnhandledAnnotatedException("unhandled");
    }

    @GetMapping(path = "/unhandled/runtime")
    public String stringWithUnhandledAnnotatedRuntimeException() {
        throw new UnhandledAnnotatedRuntimeException();
    }

    @GetMapping("/runtime")
    public void voidWithRuntimeException() {
        throw new RuntimeException();
    }

    @GetMapping("/unannotated")
    public void voidWithUnannotatedException() {
        throw new HandledUnannotatedException();
    }

    @GetMapping("/re/re")

View on GitHub (pinned to e1c734241f)

Solutions

1. If intentional (test of unmapped exceptions), expect HTTP 500 and assert on it in tests
2. Otherwise register an exception mapper: @ServerExceptionMapper for UnhandledAnnotatedException returning an appropriate status
3. Or make the endpoint not throw / return a meaningful error payload

Example fix

// before
public void voidWithUnhandledAnnotatedException() throws UnhandledAnnotatedException {
    throw new UnhandledAnnotatedException("unhandled");
}
// after
@ServerExceptionMapper
public Response map(UnhandledAnnotatedException e) {
    return Response.status(500).entity(e.getMessage()).build();
}

Response resp = given().get("/exception/unhandled/exception");
if (resp.statusCode() == 500) {
    // expected: UnhandledAnnotatedException has no registered mapper
}

When it happens

Trigger: GET /exception/unhandled/exception — the controller method always throws; there is no success path.

Common situations: Integration tests verifying 500 responses for exceptions not covered by an @ServerExceptionMapper or Spring-style @ControllerAdvice; adding a new exception type and forgetting to register a mapper.

Related errors

• Usage of multiple methods using '@RequestMapping' is not all
• Unsupported HTTP method '<method>' for @RequestMapping. Offe
• Missing required param in method '<method>'
• Could not find MessageBodyWriter for
• Could not find MessageBodyWriter for

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/9352da3c70ee9bc3. Report an issue: GitHub.