quarkusio/quarkus · error · IllegalStateException

Cannot transform exception ${failure} to a status exception

Error message

Cannot transform exception ${failure} to a status exception

What it means

AuthExceptionHandlerProvider is a default interface method: the default implementation transforms no exceptions (handlesException returns false), so calling transformToStatusException on a provider that did not override it throws this IllegalStateException. It is a programming error: you invoked a provider for an exception it declared it cannot map to a gRPC status.

Source

Thrown at extensions/grpc/runtime/src/main/java/io/quarkus/grpc/auth/AuthExceptionHandlerProvider.java:29

 * Provider for AuthExceptionHandler.
 *
 * To use a custom AuthExceptionHandler, extend {@link AuthExceptionHandler} and implement
 * an {@link AuthExceptionHandlerProvider} with priority greater than the default one.
 */
public interface AuthExceptionHandlerProvider extends Prioritized {
    int DEFAULT_PRIORITY = 0;

    <ReqT, RespT> AuthExceptionHandler<ReqT, RespT> createHandler(Listener<ReqT> listener,
            ServerCall<ReqT, RespT> serverCall, Metadata metadata);

    /**
     * @param failure security exception this provider can handle according to the {@link #handlesException(Throwable)}
     * @return status exception
     */
    default StatusException transformToStatusException(Throwable failure) {
        // because by default we don't handle any exception
        // the original behavior (before introduction of this method) is kept because 'handlesException' return false
        throw new IllegalStateException("Cannot transform exception " + failure + " to a status exception");
    }

    /**
     * @param failure any gRPC request failure
     * @return whether this provider should create response status for given failure
     */
    default boolean handlesException(Throwable failure) {
        return false;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

In your AuthExceptionHandlerProvider implementation, override transformToStatusException(Throwable) and return an appropriate StatusException (e.g. Status.UNAUTHENTICATED.withCause(failure).asException()).
Make sure handles()/handlesException() only returns true for exceptions your transformToStatusException can actually map.
Extend an existing provider (e.g. JwtAuthenticationMechanism-based providers) instead of implementing the interface from scratch if you only need small changes.
If you hit this in a test, instantiate a concrete provider rather than the interface default.

Example fix

// before
class MyProvider implements AuthExceptionHandlerProvider {
  public boolean handlesException(Throwable t) { return t instanceof MyAuthException; }
  // transformToStatusException not overridden
}
// after
@Override
public StatusException transformToStatusException(Throwable failure) {
  return Status.UNAUTHENTICATED.withDescription(failure.getMessage()).withCause(failure).asException();
}

Defensive patterns

Strategy: try-catch

Validate before calling

// before relying on a provider, verify it can transform
if (provider.getClass() == AuthExceptionHandlerProvider.class)
    throw new IllegalStateException("Default provider cannot transform exceptions; override transformToStatusException");

Type guard

boolean canTransform(AuthExceptionHandlerProvider p) {
  try { p.getClass().getMethod("transformToStatusException", Throwable.class);
        return p.getClass() != AuthExceptionHandlerProvider.class; }
  catch (NoSuchMethodException e) { return false; }
}

Try / catch

try {
    statusException = provider.transformToStatusException(failure);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Cannot transform exception")) {
        // provider didn't override the method; map the failure yourself or fix the provider
        statusException = Status.UNAUTHENTICATED.withCause(failure).asException();
    } else throw e;
}

Prevention

Always override transformToStatusException when writing a custom provider
Keep handlesException() and transformToStatusException consistent (only claim exceptions you can map)
Prefer extending an existing concrete provider over implementing the interface bare
Test the provider's transform path in unit tests

When it happens

Trigger: Calling transformToStatusException directly on a custom/default provider without overriding the method; a custom provider overrides handles() to return true for some exception but forgets to override transformToStatusException, so toStatusException falls through to the default throw.

Common situations: Implementing a custom auth exception handler for Quarkus gRPC security and overriding handles()/handlesException() but not transformToStatusException; calling the default method in tests against the bare interface.

Related errors

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