google/gson · error · RuntimeException

Unexpected IllegalAccessException occurred (Gson " + GsonBui

Error message

Unexpected IllegalAccessException occurred (Gson " + GsonBuildConfig.VERSION + "). Certain ReflectionAccessFilter features require Java >= 9 to work correctly. If you are not using ReflectionAccessFilter, report this to the Gson maintainers.

What it means

Gson treats an IllegalAccessException during normal reflective field access as an internal/should-not-happen condition. The helper createExceptionForUnexpectedIllegalAccess throws a RuntimeException noting that some ReflectionAccessFilter features need Java >= 9 and asking non-users of that filter to report the bug to Gson maintainers.

Source

Thrown at gson/src/main/java/com/google/gson/internal/reflect/ReflectionHelper.java:201

    return RECORD_HELPER.isRecord(raw);
  }

  public static String[] getRecordComponentNames(Class<?> raw) {
    return RECORD_HELPER.getRecordComponentNames(raw);
  }

  /** Looks up the record accessor method that corresponds to the given record field */
  public static Method getAccessor(Class<?> raw, Field field) {
    return RECORD_HELPER.getAccessor(raw, field);
  }

  public static <T> Constructor<T> getCanonicalRecordConstructor(Class<T> raw) {
    return RECORD_HELPER.getCanonicalRecordConstructor(raw);
  }

  public static RuntimeException createExceptionForUnexpectedIllegalAccess(
      IllegalAccessException exception) {
    throw new RuntimeException(
        "Unexpected IllegalAccessException occurred (Gson "
            + GsonBuildConfig.VERSION
            + "). Certain ReflectionAccessFilter features require Java >= 9 to work correctly. If"
            + " you are not using ReflectionAccessFilter, report this to the Gson maintainers.",
        exception);
  }

  private static RuntimeException createExceptionForRecordReflectionException(
      ReflectiveOperationException exception) {
    throw new RuntimeException(
        "Unexpected ReflectiveOperationException occurred"
            + " (Gson "
            + GsonBuildConfig.VERSION
            + ")."
            + " To support Java records, reflection is utilized to read out information"
            + " about records. All these invocations happens after it is established"
            + " that records exist in the JVM. This exception is unexpected behavior.",
        exception);

View on GitHub (pinned to 8b8628c656)

Solutions

1. Upgrade to Java 9+ if you use ReflectionAccessFilter features that require it.
2. Review your ReflectionAccessFilter configuration and ensure it matches your JVM capabilities.
3. If you do not use ReflectionAccessFilter, capture the full stack trace and file a bug with the Gson maintainers including GsonBuildConfig.VERSION from the message.
4. As a workaround, register a custom TypeAdapter for the affected type to bypass reflection.

Example fix

// before: SecurityManager + Java 8 triggers unexpected IllegalAccessException
Gson gson = new GsonBuilder().addReflectionAccessFilter(...).create();

// after: upgrade runtime and simplify filter usage
Gson gson = new GsonBuilder().create(); // drop filter or run on Java 9+

// Best-effort: detect restrictive runtime before Gson use.
boolean isJava9OrLater() {
  String v = System.getProperty("java.specification.version");
  return v != null && (v.matches("[9-9]\\d*") || v.startsWith("1.8") == false && Integer.parseInt(v.split("\\.")[0]) >= 9);
}

static boolean reflectionFilterSafeOnThisJvm(boolean usesFilter) { return !usesFilter || isJava9OrLater(); }

try {
  T obj = gson.fromJson(json, type);
} catch (RuntimeException e) {
  if (e.getMessage().contains("Unexpected IllegalAccessException")) {
    // upgrade JVM or drop ReflectionAccessFilter; report to Gson if neither applies
  } else throw e;
}

When it happens

Trigger: An IllegalAccessException escapes Gson's normal makeAccessible flow on a JVM/configuration where it should not occur; most likely on Java 8 with a SecurityManager or an unusual module setup combined with ReflectionAccessFilter.

Common situations: Running Gson with a restrictive SecurityManager, mixing ReflectionAccessFilter with an older JVM, or hitting a genuine Gson bug in an unusual reflection scenario.

Related errors

• Unexpected ReflectiveOperationException occurred (Gson " + G
• Primitive type is not allowed
• Must specify owner type for {rawType}
• At most one lower bound is supported
• Exactly one upper bound must be specified

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/279ac4d36e96a53b.json. Report an issue: GitHub.