{"record":{"id":"3806a9e6889872ea","repo":"google/gson","slug":"unexpected-illegalaccessexception-occurred-gson","errorCode":null,"errorMessage":"Unexpected IllegalAccessException occurred (Gson {}). Certain ReflectionAccessFilter features require Java >= 9 to work correctly. If you are not using ReflectionAccessFilter, report this to the Gson maintainers.","messagePattern":"Unexpected IllegalAccessException occurred \\(Gson (.+?)\\)\\. Certain ReflectionAccessFilter features require Java >= 9 to work correctly\\. If you are not using ReflectionAccessFilter, report this to the Gson maintainers\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"gson/src/main/java/com/google/gson/internal/reflect/ReflectionHelper.java","lineNumber":201,"sourceCode":"    return RECORD_HELPER.isRecord(raw);\n  }\n\n  public static String[] getRecordComponentNames(Class<?> raw) {\n    return RECORD_HELPER.getRecordComponentNames(raw);\n  }\n\n  /** Looks up the record accessor method that corresponds to the given record field */\n  public static Method getAccessor(Class<?> raw, Field field) {\n    return RECORD_HELPER.getAccessor(raw, field);\n  }\n\n  public static <T> Constructor<T> getCanonicalRecordConstructor(Class<T> raw) {\n    return RECORD_HELPER.getCanonicalRecordConstructor(raw);\n  }\n\n  public static RuntimeException createExceptionForUnexpectedIllegalAccess(\n      IllegalAccessException exception) {\n    throw new RuntimeException(\n        \"Unexpected IllegalAccessException occurred (Gson \"\n            + GsonBuildConfig.VERSION\n            + \"). Certain ReflectionAccessFilter features require Java >= 9 to work correctly. If\"\n            + \" you are not using ReflectionAccessFilter, report this to the Gson maintainers.\",\n        exception);\n  }\n\n  private static RuntimeException createExceptionForRecordReflectionException(\n      ReflectiveOperationException exception) {\n    throw new RuntimeException(\n        \"Unexpected ReflectiveOperationException occurred\"\n            + \" (Gson \"\n            + GsonBuildConfig.VERSION\n            + \").\"\n            + \" To support Java records, reflection is utilized to read out information\"\n            + \" about records. All these invocations happens after it is established\"\n            + \" that records exist in the JVM. This exception is unexpected behavior.\",\n        exception);","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/google/gson/blob/310ac341f2f92a454b229bf21f70d2d18b2b6db7/gson/src/main/java/com/google/gson/internal/reflect/ReflectionHelper.java#L183-L219","documentation":"Thrown by ReflectionHelper.createExceptionForUnexpectedIllegalAccess when reflection on a field produces an IllegalAccessException that the ReflectionAccessFilter machinery cannot handle. The message notes that certain ReflectionAccessFilter features need Java >= 9, and asks non-users of ReflectionAccessFilter to report the bug to Gson maintainers. This is a defensive 'this should never happen' path.","triggerScenarios":"A configured ReflectionAccessFilter is in use, but the JVM is older than Java 9 (where the filter relies on APIs that do not exist), or a field access fails in an unexpected way not covered by the filter's allowance logic. Also possible on early-access or buggy JDKs.","commonSituations":"Running on Java 8 with a ReflectionAccessFilter configured for Java 9+ semantics; custom ReflectionAccessFilter implementations that mishandle field access; obscure JDK reflection bugs; mismatched Gson version expecting features the JVM lacks.","solutions":["If on Java 8, either upgrade to Java 9+ or remove/disable the ReflectionAccessFilter that requires it.","Ensure the ReflectionAccessFilter you configured actually permits access for the affected type.","Register a custom TypeAdapter/InstanceCreator for the failing type to bypass reflection entirely.","If you are not using ReflectionAccessFilter, capture the full stack trace and Gson version and report to the Gson maintainers as the message instructs."],"exampleFix":"// before: ReflectionAccessFilter configured on Java 8 -> unexpected IllegalAccessException\nGson g = new GsonBuilder()\n  .addReflectionAccessFilter(ReflectionAccessFilter.BLOCK_ALL_PLATFORM)\n  .create();\n\n// after: drop the filter on Java 8, or move to Java 9+\nGson g = new GsonBuilder().create(); // no filter\n\n// or supply a custom InstanceCreator to avoid reflection:\nGson g = new GsonBuilder()\n  .registerTypeAdapter(MyType.class, (InstanceCreator<MyType>) t -> new MyType())\n  .create();","handlingStrategy":"try-catch","validationCode":"// verify JVM version suitability before enabling filter features\nif (ReflectionAccessFilter.class.getModule().isNamed() && Runtime.version().feature() < 9) {\n  throw new IllegalStateException(\"ReflectionAccessFilter features require Java >= 9\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  return gson.fromJson(json, Type.class);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Unexpected IllegalAccessException occurred\")) {\n    // remove ReflectionAccessFilter or upgrade JVM; do NOT silently retry the same Gson\n    throw new IllegalStateException(\"ReflectionAccessFilter/JVM mismatch\", e);\n  }\n  throw e;\n}","preventionTips":["Do not configure a ReflectionAccessFilter on Java 8.","Pin Gson + JVM versions together in CI and run a reflection smoke test.","Provide InstanceCreators for sensitive types to avoid reflection entirely.","If this fires, capture the full stack trace and report per the message."],"tags":["gson","reflection","reflection-access-filter","java-version","runtime-exception","illegal-access"],"backgroundTag":null,"analyzedSha":"310ac341f2f92a454b229bf21f70d2d18b2b6db7","analyzedAt":"2026-08-10T02:58:47.455Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}