What causes "Cannot override built-in adapter for ${type}" in google/gson?

Do not register an adapter for Object.class; target the concrete type you need.

google/gson · error · IllegalArgumentException

Cannot override built-in adapter for

Error message

Cannot override built-in adapter for ${type}

What it means

Thrown by GsonBuilder.registerTypeAdapter(Type, Object) when attempting to register an adapter for a type whose built-in adapter is non-overridable. Currently hasNonOverridableAdapter returns true for Object.class, so registering a custom adapter for Object.class is rejected with an IllegalArgumentException. This prevents breaking Gson's core Object handling.

Solutions

Do not register an adapter for Object.class; target the concrete type you need.
If you need to customize broadly, register a TypeAdapterFactory that inspects the type and handles only the ones you care about.
Use registerTypeHierarchyAdapter for a specific base class/interface instead of Object.
Check that the Type you pass is not Object.class (e.g. capture generic type via TypeToken).

Example fix

// before
builder.registerTypeAdapter(Object.class, myAdapter); // throws

// after
builder.registerTypeHierarchyAdapter(MyBase.class, myAdapter);

Defensive patterns

Strategy: validation

Validate before calling

// Reject Object.class before registering
if (type.equals(Object.class)) {
  throw new IllegalArgumentException("Cannot override built-in adapter for Object.class");
}
builder.registerTypeAdapter(type, adapter);

Try / catch

try { builder.registerTypeAdapter(type, adapter); }
catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Cannot override built-in adapter")) {
    // target a concrete type, or use registerTypeHierarchyAdapter / a factory
  } else throw e;
}

Prevention

Never register an adapter for Object.class.
Use a TypeAdapterFactory that filters by type instead.
For broad behavior, register a hierarchy adapter on a specific base class.

When it happens

Trigger: Calling registerTypeAdapter(Object.class, adapter); attempting to override Object.class (sometimes done by accident when a Type resolves to Object).

Common situations: Generic deserialization where TypeToken.getRawType() resolves to Object; trying to globally intercept all values via Object.class; registering an adapter keyed by a Type variable that erases to Object.

Related errors

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

Appendix: source

Thrown at gson/src/main/java/com/google/gson/GsonBuilder.java:754

   *     class or {@link JsonElement} or any of its subclasses
   * @see #registerTypeHierarchyAdapter(Class, Object)
   */
  @CanIgnoreReturnValue
  public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter) {
    Objects.requireNonNull(type);
    Objects.requireNonNull(typeAdapter);
    if (!(typeAdapter instanceof JsonSerializer<?>
        || typeAdapter instanceof JsonDeserializer<?>
        || typeAdapter instanceof InstanceCreator<?>
        || typeAdapter instanceof TypeAdapter<?>)) {
      throw new IllegalArgumentException(
          "Class "
              + typeAdapter.getClass().getName()
              + " does not implement any supported type adapter class or interface");
    }

    if (hasNonOverridableAdapter(type)) {
      throw new IllegalArgumentException("Cannot override built-in adapter for " + type);
    }

    if (typeAdapter instanceof InstanceCreator<?>) {
      instanceCreators.put(type, (InstanceCreator<?>) typeAdapter);
    }
    if (typeAdapter instanceof JsonSerializer<?> || typeAdapter instanceof JsonDeserializer<?>) {
      TypeToken<?> typeToken = TypeToken.get(type);
      factories.add(TreeTypeAdapter.newFactoryWithMatchRawType(typeToken, typeAdapter));
    }
    if (typeAdapter instanceof TypeAdapter<?>) {
      @SuppressWarnings({"unchecked", "rawtypes"})
      TypeAdapterFactory factory =
          TypeAdapters.newFactory(TypeToken.get(type), (TypeAdapter) typeAdapter);
      factories.add(factory);
    }
    return this;
  }

View on GitHub (pinned to 310ac341f2)