What causes "Failed to redefine module ${moduleName}" in quarkusio/quarkus?

Run the build on a current, standard JDK LTS (17/21) from a mainstream vendor

quarkusio/quarkus · error · RuntimeException

Failed to redefine module

Error message

Failed to redefine module ${moduleName}

What it means

AgentBasedModulesReconfigurer uses the JVM's Agent-based Module.redefineModule API to open JPMS packages so Quarkus deployment code can access them. If redefining a source module throws for any reason, it is wrapped as this RuntimeException. It means the build could not relax module boundaries for the named module.

Solutions

Run the build on a current, standard JDK LTS (17/21) from a mainstream vendor
Add explicit --add-opens flags on the build JVM for the packages the error mentions, avoiding the need for redefinition
Verify the package names exist in the named module (jar --describe-module or java --list-modules)
Remove SecurityManager/agent restrictions that could reject module redefinition

Example fix

// before
./mvnw install   # custom JDK build rejects redefineModule
// after
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
./mvnw install -DargLine="--add-opens java.base/java.lang=ALL-UNNAMED"

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the package exists in the module before attempting redefinition
Module m = sourceModule;
String pkg = packageName;
if (m.getNamed() && !m.isExported(pkg) && m.getPackages() != null && !Set.of(m.getPackages()).contains(pkg)) {
    throw new IllegalArgumentException("Package " + pkg + " not defined by module " + m.getName());
}

Try / catch

try {
    // deployment proceeds; AgentBasedModulesReconfigurer runs internally
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to redefine module")) {
        log.errorf(e, "Module redefinition failed for %s - consider explicit --add-opens", e.getMessage());
    }
    throw e;
}

Prevention

Use a standard, current LTS JDK from a mainstream vendor for builds
Add explicit --add-opens flags instead of relying on agent-based redefinition
Confirm packages with java --describe-module before scanning-based opens
Remove SecurityManager or restrictive agent configurations from the build JVM

When it happens

Trigger: During openJavaModules(), Module.redefineModule is invoked with computed open instructions for a module and the JVM rejects the call (module is not resolvable/already closed, invalid package name, security manager denial, or any other Exception from redefineModule).

Common situations: Unusual JDK builds (early access, hardened images) that restrict module redefinition; running with a SecurityManager or restrictive agent policies; packages computed from classpath scanning that do not exist in the target module; mismatched JDK versions where expected packages were removed.

Related errors

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

Appendix: source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/jvm/AgentBasedModulesReconfigurer.java:113

        if (logger.isDebugEnabled()) {
            openInstructions.forEach(
                    (pkg, modules) -> logger.debugf("Opening package %s of %s to modules %s", pkg, sourceModule, modules));
        }
        try {
            // We are redefining the target module, adding a new "open"
            // rule for it.
            //This method is additive: we don't need to read previous reads and exports
            //to avoid losing them.
            instrumentation.redefineModule(
                    sourceModule, // The module to change
                    Set.of(), // Extra reads
                    Map.of(), // Extra exports
                    openInstructions, // The relevant one
                    Set.of(), // Extra uses
                    Map.of() // Extra provides
            );
        } catch (Exception e) {
            throw new RuntimeException("Failed to redefine module " + sourceModule.getName());
        }
    }

    // A convenience container to keep our logic above more readable
    private static class PerModuleOpenInstructions {
        private final Map<String, Set<Module>> modulesToOpenToByPackage = new HashMap<>();

        public void addOpens(final String packageName, final Module openingModule) {
            final Set<Module> modulesToOpenTo = modulesToOpenToByPackage.computeIfAbsent(packageName, k -> new HashSet<>());
            modulesToOpenTo.add(openingModule);
        }
    }

    /**
     * This isn't going to transform any class, but we leverage the existing agent
     * and register as a callback to provide useful diagnostics: we can detect new
     * unnamed modules being created and log them.
     * Obviously this has a cost, so register this only when the matching log level is enabled.

View on GitHub (pinned to e1c734241f)