{"record":{"id":"80917799acdc2f0d","repo":"quarkusio/quarkus","slug":"add-awt-quarkus-extension-to-enable-java2d-imageio","errorCode":null,"errorMessage":"Add AWT Quarkus extension to enable Java2D/ImageIO. Additional system libraries such as `freetype' and `fontconfig' might be needed.","messagePattern":"Add AWT Quarkus extension to enable Java2D/ImageIO\\. Additional system libraries such as `freetype' and `fontconfig' might be needed\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/runtime/src/main/java/io/quarkus/runtime/graal/AwtImageIO.java","lineNumber":45,"sourceCode":"     */\n    static final class IsAWTAbsent implements BooleanSupplier {\n        @Override\n        public boolean getAsBoolean() {\n            try {\n                Class.forName(\"io.quarkus.awt.runtime.JDKSubstitutions\");\n                return false;\n            } catch (ClassNotFoundException e) {\n                return true;\n            }\n        }\n    }\n}\n\n@TargetClass(className = \"java.awt.GraphicsEnvironment\", onlyWith = AwtImageIO.IsAWTAbsent.class)\nfinal class Target_java_awt_GraphicsEnvironment {\n    @Substitute\n    public static GraphicsEnvironment getLocalGraphicsEnvironment() {\n        throw new UnsupportedOperationException(AwtImageIO.AWT_EXTENSION_HINT);\n    }\n\n    @Substitute\n    public static boolean isHeadless() {\n        throw new UnsupportedOperationException(AwtImageIO.AWT_EXTENSION_HINT);\n    }\n}\n\n@TargetClass(className = \"java.awt.Toolkit\", onlyWith = AwtImageIO.IsAWTAbsent.class)\nfinal class Target_java_awt_Toolkit {\n    @Substitute\n    public static synchronized Toolkit getDefaultToolkit() {\n        throw new UnsupportedOperationException(AwtImageIO.AWT_EXTENSION_HINT);\n    }\n}\n\n@TargetClass(className = \"java.awt.Color\", onlyWith = AwtImageIO.IsAWTAbsent.class)\nfinal class Target_java_awt_Color {","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/runtime/src/main/java/io/quarkus/runtime/graal/AwtImageIO.java#L27-L63","documentation":"When the AWT/Java2D classes are absent from the native image (IsAWTAbsent condition), Quarkus substitutes GraphicsEnvironment.getLocalGraphicsEnvironment() with a stub that throws UnsupportedOperationException with a hint to add the AWT extension. This is a Graal @Substitute placeholder, not a bug in user code.","triggerScenarios":"Calling GraphicsEnvironment.getLocalGraphicsEnvironment() at runtime in a native executable built without AWT support (the io.quarkus:quarkus-awt extension not present).","commonSituations":"Libraries using ImageIO, fonts, or BufferedImage (PDF generation, barcode/captcha rendering) that touch GraphicsEnvironment during native execution; works on JVM mode but fails in native-image because AWT was excluded.","solutions":["Add the AWT extension: ./mvnw quarkus:add-extension -Dextensions=\"io.quarkus:quarkus-awt\" (or add io.quarkus:quarkus-awt to pom.xml) and rebuild the native image.","Ensure the container/base image used for the native build and runtime includes freetype and fontconfig system libraries.","Avoid code paths that initialize AWT (e.g. headless graphics, font metrics) if images are not actually needed."],"exampleFix":"// before (pom.xml)\n<dependencies>...</dependencies>\n// after\n<dependency>\n  <groupId>io.quarkus</groupId>\n  <artifactId>quarkus-awt</artifactId>\n</dependency>","handlingStrategy":"try-catch","validationCode":"// At startup, fail fast if AWT is needed but absent:\nstatic {\n    try {\n        Class.forName(\"java.awt.GraphicsEnvironment\");\n    } catch (ClassNotFoundException e) {\n        throw new IllegalStateException(\"AWT classes missing: add the quarkus-awt extension\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"AWT Quarkus extension\")) {\n        throw new IllegalStateException(\"Add io.quarkus:quarkus-awt and rebuild the native image\", e);\n    }\n    throw e;\n}","preventionTips":["Add io.quarkus:quarkus-awt whenever any dependency uses AWT/ImageIO/2D graphics.","Test the native build (not just JVM mode) when image processing is involved.","Keep freetype and fontconfig installed in build and runtime container images.","Document the AWT requirement in your project's build configuration."],"tags":["native-image","awt","graal-substitute"],"backgroundTag":"missing-awt-extension","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"}