{"record":{"id":"ad557ff03316ed3c","repo":"quarkusio/quarkus","slug":"jmx-is-not-available-in-native-images","errorCode":null,"errorMessage":"JMX is not available in native images.","messagePattern":"JMX is not available in native images\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/graal/Substitute_CacheProxy.java","lineNumber":17,"sourceCode":"package io.quarkus.hibernate.orm.runtime.graal;\n\nimport com.github.benmanes.caffeine.jcache.CacheProxy;\nimport com.oracle.svm.core.annotate.Substitute;\nimport com.oracle.svm.core.annotate.TargetClass;\n\n/**\n * Removes some caffeine-jcache features related to JMX,\n * because we don't want to put in the work to make that work in native mode.\n */\n// TODO should this be in quarkus-caffeine, with caffeine-jcache as a \"provided\" dependency?\n@TargetClass(CacheProxy.class)\nfinal class Substitute_CacheProxy {\n    @Substitute\n    void enableManagement(boolean enabled) {\n        if (enabled) {\n            throw new IllegalStateException(\"JMX is not available in native images.\");\n        }\n    }\n\n    @Substitute\n    void enableStatistics(boolean enabled) {\n        if (enabled) {\n            throw new IllegalStateException(\"JMX is not available in native images.\");\n        }\n    }\n}\n","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/graal/Substitute_CacheProxy.java#L1-L28","documentation":"In native images Quarkus substitutes Caffeine JCache's CacheProxy.enableManagement() because JMX is unavailable in native mode. The substitute throws an IllegalStateException if management (JMX exposure of the cache) is requested with enabled=true, instead of silently enabling it.","triggerScenarios":"Running a native-image build and enabling JMX management for a Caffeine JCache — e.g. via cache configuration setManagementEnabled(true) or JMX-related cache properties — which invokes the substituted enableManagement(true).","commonSituations":"Porting a JVM-mode app to native where caches had JMX statistics/management enabled in configuration; enabling JMX monitoring code paths unconditionally in shared cache setup code.","solutions":["Disable cache JMX management when running in native mode (setManagementEnabled(false) or remove the JMX config property).","Gate the JMX-enabling code behind a runtime check for native image, enabling it only on the JVM.","Use alternative monitoring (e.g. Micrometer metrics exposed by Quarkus) instead of JMX in native mode.","Only call enableManagement when users explicitly opt into JMX via configuration that defaults to off."],"exampleFix":"// before\ncache.enableManagement(true);\n\n// after\nif (!ImageInfo.inImageCode()) {\n  cache.enableManagement(true);\n}","handlingStrategy":"fallback","validationCode":"// Only enable JMX management when not running as a native image\nif (!io.quarkus.runtime.ImageInfo.inImageCode()) {\n    cache.setManagementEnabled(true);\n}","typeGuard":null,"tryCatchPattern":"try {\n    cache.enableManagement(true);\n} catch (IllegalStateException e) {\n    if (\"JMX is not available in native images.\".equals(e.getMessage())) {\n        log.info(\"Skipping cache JMX management in native mode; using Micrometer instead\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Gate all JMX-enabling code with io.quarkus.runtime.ImageInfo.inImageCode()","Default cache management/statistics flags to off in configuration","Use Micrometer metrics for cache observability in native mode"],"tags":["native-image","jmx","caffeine","jcache","quarkus","graalvm"],"backgroundTag":"jmx-unavailable-in-native","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"}