{"record":{"id":"efc6dac5e2e24854","repo":"quarkusio/quarkus","slug":"using-unwrapexception-without-a-value-is-only-sup","errorCode":null,"errorMessage":"Using @UnwrapException without a value is only supported on exception classes. Offending target is '${classInfo.name()}'.","messagePattern":"Using @UnwrapException without a value is only supported on exception classes\\. Offending target is '(.+?)'\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java","lineNumber":177,"sourceCode":"                    throw new IllegalStateException(\n                            \"@UnwrapException is only supported on classes. Offending target is: \" + target);\n                }\n                ClassInfo classInfo = target.asClass();\n                ClassInfo toCheck = classInfo;\n                boolean isException = false;\n                while (true) {\n                    DotName superDotName = toCheck.superName();\n                    if (EXCEPTION.equals(superDotName) || RUNTIME_EXCEPTION.equals(superDotName)) {\n                        isException = true;\n                        break;\n                    }\n                    toCheck = index.getClassByName(superDotName);\n                    if (toCheck == null) {\n                        break;\n                    }\n                }\n                if (!isException) {\n                    throw new IllegalArgumentException(\n                            \"Using @UnwrapException without a value is only supported on exception classes. Offending target is '\"\n                                    + classInfo.name() + \"'.\");\n                }\n\n                producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString(), strategy));\n            } else {\n                Type[] exceptionTypes = value.asClassArray();\n                for (Type exceptionType : exceptionTypes) {\n                    producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString(), strategy));\n                }\n            }\n        }\n    }\n\n    private static ExceptionUnwrapStrategy toExceptionUnwrapStrategy(AnnotationValue strategyValue) {\n        if (strategyValue != null) {\n            return ExceptionUnwrapStrategy.valueOf(strategyValue.asEnum());\n        }","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java#L159-L195","documentation":"When @UnwrapException is used without a value on a class, Quarkus requires the class (or one of its superclasses) to be a java.lang.Exception/Throwable type, since the class itself is treated as the exception to unwrap. If the hierarchy walk never reaches an exception type, deployment fails with this IllegalArgumentException.","triggerScenarios":"@UnwrapException (no value) is placed on a class that does not extend Throwable/Exception (checked by walking superclasses in the Jandex index; also breaks early if a superclass is not in the index), e.g. on a plain POJO or a resource class.","commonSituations":"Annotating a wrapper class that is not an exception, intending custom unwrapping logic; renaming/refactoring so the annotated class no longer extends Exception; missing superclass in the index (separate module not indexed).","solutions":["Make the annotated class extend RuntimeException or another Throwable subtype","Provide an explicit value naming the exception to unwrap: @UnwrapException(MyException.class)","Remove @UnwrapException if the class is not involved in exception unwrapping","If a superclass should have matched, ensure it is part of the Quarkus index (proper module dependency, not an unindexed jar)"],"exampleFix":"// before\n@UnwrapException\npublic class ResultWrapper { ... }\n// after\n@UnwrapException\npublic class ResultWrapper extends RuntimeException { ... }","handlingStrategy":"validation","validationCode":"UnwrapException u = clazz.getAnnotation(UnwrapException.class);\nif (u != null && u.value() == UnwrapException.class /* no value */\n        && !Throwable.class.isAssignableFrom(clazz))\n    throw new IllegalStateException(clazz + \" uses @UnwrapException without value but is not an exception class\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure classes annotated with value-less @UnwrapException extend Exception/RuntimeException","Otherwise pass the target exception type as the annotation value","Keep exception hierarchies in indexed application modules so superclass checks succeed"],"tags":["exceptions","annotations","resteasy-reactive","quarkus","unwrap-exception"],"backgroundTag":"unwrap-exception-misuse","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}