How To Fix Java 21 Module-Info.Java Compilation Error [So...

Issue	Common Root Cause	Quick Fix
Module Not Found	Missing `--module-path` in compiler args.	Add the path to your dependencies using the `-p` flag.
Package Not Visible	Missing `exports` or `requires` directive.	Add `requires module.name;` to `module-info.java`.
Invalid Flag Error	JDK version mismatch (using Java 8/11 syntax).	Update `JAVA_HOME` to JDK 21 and check preview features.

Table of Contents

What is the Java 21 module-info.java compilation error?

The Java 21 module-info.java compilation error occurs when the Java Compiler (javac) fails to process the module descriptor file. This file is the heart of the Java Platform Module System (JPMS).

Commonly, these errors arise because the compiler cannot locate a required module on the module path or because of strict encapsulation rules introduced in later Java versions. Java 21 maintains these strict boundaries to ensure better security and performance.

Errors often manifest as “error: module not found” or “error: package is defined in module X, but module Y does not read it.” These are design-time safeguards to prevent illegal access between codebases.

Step-by-Step Solutions

1. Correct the Module Path Configuration

In Java 21, dependencies must be on the module path, not the classpath, if you are using modularity. Ensure you are using the correct flag during compilation.

javac --module-path libs -d out src/module-info.java src/com/example/*.java

2. Verify ‘requires’ and ‘exports’ Directives

Check your module-info.java syntax. If you are using a library, you must explicitly require it. If you want others to use your code, you must export the package.

module my.module {
    requires java.sql;
    requires common.library;
    exports com.my.package;
}

3. Update Maven or Gradle Compiler Plugins

If you use a build tool, the error often stems from an outdated compiler plugin. Ensure your pom.xml specifies Java 21 and the latest plugin version.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <release>21</release>
    </configuration>
</plugin>

4. Handle Transitive Dependencies

If your module relies on a module that relies on another, use the requires transitive keyword. This allows any module reading your module to also read the dependency automatically.

module my.api {
    requires transitive other.library;
}