java runtime_error ai_generated true

java.lang.IllegalAccessError: class X cannot access class Y

ID: java/illegal-access-error

Also available as: JSON · Markdown
80%Fix Rate
86%Confidence
75Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

IllegalAccessError occurs when code tries to access a class, method, or field that is not accessible due to Java module system (JPMS) encapsulation or access modifier restrictions. Very common after migrating to JDK 17+ from JDK 8, where internal APIs were freely accessible.

generic

Workarounds

  1. 88% success Add --add-opens or --add-exports JVM flags to open specific module packages 
    1. Read the error message to identify which module and package are involved (e.g., 'module java.base does not export sun.misc to unnamed module'). 2. Add --add-opens java.base/sun.misc=ALL-UNNAMED (for reflective access) or --add-exports java.base/sun.misc=ALL-UNNAMED (for compile-time access). 3. Add to JVM startup flags in your run script, Dockerfile, or Maven/Gradle configuration. 4. Document the flags so future maintainers understand why they are needed.
  2. 85% success Replace usage of internal JDK APIs with public, supported alternatives 
    1. Identify which internal API is being accessed (e.g., sun.misc.Unsafe, com.sun.*, jdk.internal.*). 2. Find the public replacement: Unsafe → VarHandle (JDK 9+), sun.misc.BASE64Encoder → java.util.Base64. 3. If a library is using the internal API, upgrade to a version that supports JDK 17+ module system. 4. This is the preferred long-term fix over --add-opens flags.

Dead Ends

Common approaches that don't work:

  1. Adding --illegal-access=permit to JVM flags on JDK 17+ 95% fail

    The --illegal-access flag was removed in JDK 17. It was only available in JDK 9-16 as a migration aid. On JDK 17+, this flag is not recognized and the JVM will either ignore it or fail to start.

  2. Downgrading to JDK 8 to avoid module system restrictions 70% fail

    JDK 8 is past its public support end-of-life. While this removes module restrictions, it gives up 9 years of security patches, performance improvements, and language features. It is not a sustainable solution.

Error Chain

Leads to:
Preceded by:
Frequently confused with: