google/gson · critical · RuntimeException

Unable to create instance of {rawType}. Registering an Insta

Error message

Unable to create instance of {rawType}. Registering an InstanceCreator or a TypeAdapter for this type, or adding a no-args constructor may fix this problem.

What it means

When no no-args constructor and no InstanceCreator exist, Gson falls back to sun.misc.Unsafe.allocateInstance (if enabled). If that fails (UnsupportedOperationException on JVMs without sun.misc.Unsafe, module-access denial, or final-field issues) it wraps the cause as RuntimeException advising to register an InstanceCreator or TypeAdapter or add a no-args constructor.

Source

Thrown at gson/src/main/java/com/google/gson/internal/ConstructorConstructor.java:369

    }
    // Then try ConcurrentNavigableMap implementation
    else if (rawType.isAssignableFrom(ConcurrentSkipListMap.class)) {
      return ConcurrentSkipListMap::new;
    }

    // Was unable to create matching Map constructor
    return null;
  }

  private <T> ObjectConstructor<T> newUnsafeAllocator(Class<? super T> rawType) {
    if (useJdkUnsafe) {
      return () -> {
        try {
          @SuppressWarnings("unchecked")
          T newInstance = (T) UnsafeAllocator.INSTANCE.newInstance(rawType);
          return newInstance;
        } catch (Exception e) {
          throw new RuntimeException(
              ("Unable to create instance of "
                  + rawType
                  + ". Registering an InstanceCreator or a TypeAdapter for this type, or adding a"
                  + " no-args constructor may fix this problem."),
              e);
        }
      };
    } else {
      String exceptionMessage =
          "Unable to create instance of "
              + rawType
              + "; usage of JDK Unsafe is disabled. Registering an InstanceCreator or a TypeAdapter"
              + " for this type, adding a no-args constructor, or enabling usage of JDK Unsafe may"
              + " fix this problem.";

      // Check if R8 removed all constructors
      if (rawType.getDeclaredConstructors().length == 0) {
        // R8 with Unsafe disabled might not be common enough to warrant a separate Troubleshooting

View on GitHub (pinned to 8b8628c656)

Solutions

1. Add an accessible no-args constructor to the class.
2. Register an InstanceCreator<T> that returns a properly constructed instance.
3. Register a TypeAdapter<T> that builds the object via the existing required-args constructor.
4. If appropriate, allow JDK Unsafe via the GsonBuilder configuration or module opens.

Example fix

// before
public final class User { /* only User(String, String) exists */ }

// after (option A: InstanceCreator)
Gson gson = new GsonBuilder()
    .registerTypeAdapter(User.class, (InstanceCreator<User>) t -> new User("", ""))
    .create();

try {
  rawType.getDeclaredConstructor(); // no-args constructor exists?
} catch (NoSuchMethodException e) {
  // must register InstanceCreator or TypeAdapter
}

boolean hasNoArgsConstructor(Class<?> c) {
  try { c.getDeclaredConstructor(); return true; }
  catch (NoSuchMethodException e) { return false; }
}

try {
  return gson.fromJson(json, type);
} catch (RuntimeException ex) {
  if (ex.getMessage().startsWith("Unable to create instance")) {
    // register InstanceCreator and retry
  }
  throw ex;
}

When it happens

Trigger: Deserializing a class with no no-args constructor on a JVM/manifest where Unsafe is blocked or unavailable (recent JDKs with --illegal-access=deny, GraalVM, some Android runtimes, modules sealing the package).

Common situations: Upgrading JDK (Unsafe restrictions); running on GraalVM/native-image; R8/ProGuard stripping constructors; record classes or classes with only required-args constructors.

Related errors

• Failed to invoke constructor '{constructor}' with no args
• Cannot allocate {c}. Usage of JDK sun.misc.Unsafe is enabled
• Invalid EnumSet type: {type}
• Invalid EnumMap type: {type}
• Cannot set value of 'static final' " + fieldDescription

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