google/gson · error · JsonIOException

Unable to create instance of ${rawType}; Register an Instanc

Error message

Unable to create instance of ${rawType}; Register an InstanceCreator or a TypeAdapter for this type.

What it means

Thrown when the type has no accessible no-args constructor, no InstanceCreator, no special collection constructor, and allowUnsafe is false. This comes from ConstructorConstructor.get(typeToken, false), which disallows the Unsafe fallback. The message suggests registering an InstanceCreator or TypeAdapter.

Source

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

   * ObjectConstructor}, which would then choose another way of creating the object. And it supports
   * types which are only serialized but not deserialized (compared to directly throwing an
   * exception when the {@code ObjectConstructor} is requested), e.g. when the runtime type of an
   * object is inaccessible, but the compile-time type is accessible.
   */
  private static final class ThrowingObjectConstructor<T> implements ObjectConstructor<T> {
    private final String exceptionMessage;

    ThrowingObjectConstructor(String exceptionMessage) {
      this.exceptionMessage = exceptionMessage;
    }

    @Override
    public T construct() {
      // New exception is created every time to avoid keeping a reference to an exception with
      // potentially long stack trace, causing a memory leak
      // (which would happen if the exception was already created when the
      // `ThrowingObjectConstructor` is created)
      throw new JsonIOException(exceptionMessage);
    }
  }

  private static final class InstanceCreatorConstructor<T> implements ObjectConstructor<T> {
    private final InstanceCreator<T> instanceCreator;
    private final Type type;

    InstanceCreatorConstructor(InstanceCreator<T> instanceCreator, Type type) {
      this.instanceCreator = instanceCreator;
      this.type = type;
    }

    @Override
    public T construct() {
      return instanceCreator.createInstance(type);
    }
  }
}

View on GitHub (pinned to 310ac341f2)

Solutions

  1. Add a no-args constructor to the class
  2. Register an InstanceCreator for the type
  3. Register a custom TypeAdapter for the type
  4. If you control the call, use the single-arg get(typeToken) which allows Unsafe

Example fix

// before - type has only a parameterized ctor, get(.., false)
constructorConstructor.get(typeToken, false);

// after - register InstanceCreator or add no-args ctor
gsonBuilder.registerTypeAdapter(MyType.class, myInstanceCreator);
// OR
class MyType { public MyType() {} }
Defensive patterns

Strategy: validation

Validate before calling

// If calling get(typeToken, false), ensure the type has a no-args ctor or InstanceCreator
Class<?> c = typeToken.getRawType();
boolean hasNoArgs;
try { c.getDeclaredConstructor(); hasNoArgs = true; }
catch (NoSuchMethodException e) { hasNoArgs = false; }
if (!hasNoArgs && !hasInstanceCreator(c)) {
  throw new IllegalStateException(c + " needs no-args ctor or InstanceCreator (Unsafe disallowed)");
}

Try / catch

try {
  return constructorConstructor.get(typeToken, false).construct();
} catch (JsonIOException e) {
  if (e.getMessage().startsWith("Unable to create instance") && e.getMessage().contains("Register an InstanceCreator")) {
    throw new MyParseException("allowUnsafe=false requires no-args ctor for " + typeToken, e);
  }
  throw e;
}

Prevention

When it happens

Trigger: ConstructorConstructor.get(typeToken, false) is called for a concrete, non-abstract type that lacks a no-args constructor and InstanceCreator; the false allowUnsafe parameter prevents the Unsafe fallback.

Common situations: Internal Gson code paths that deliberately disallow Unsafe (e.g. specific deserializers calling the two-arg get); testing utilities; library code that wants strict construction semantics.

Related errors

AI-assisted analysis of google/gson@310ac341f2 (2026-08-10). Data as JSON: /api/errors/d8dc88305416129e. Report an issue: GitHub.