google/gson · error · IllegalArgumentException

GSON ({GsonBuildConfig.VERSION}) cannot handle {type}

Error message

GSON ({GsonBuildConfig.VERSION}) cannot handle {type}

What it means

Thrown by Gson.getAdapter(TypeToken) when NO registered TypeAdapterFactory (including Gson's built-in factories) returns a non-null adapter for the requested type. This means Gson has no way to serialize or deserialize the given type. The message embeds the running Gson version for support purposes. It is an IllegalArgumentException, typically surfaced from toJson/fromJson.

Source

Thrown at gson/src/main/java/com/google/gson/Gson.java:385

      threadCalls.put(type, call);

      for (TypeAdapterFactory factory : factories) {
        candidate = factory.create(this, type);
        if (candidate != null) {
          call.setDelegate(candidate);
          // Replace future adapter with actual adapter
          threadCalls.put(type, candidate);
          break;
        }
      }
    } finally {
      if (isInitialAdapterRequest) {
        threadLocalAdapterResults.remove();
      }
    }

    if (candidate == null) {
      throw new IllegalArgumentException(
          "GSON (" + GsonBuildConfig.VERSION + ") cannot handle " + type);
    }

    if (isInitialAdapterRequest) {
      /*
       * Publish resolved adapters to all threads
       * Can only do this for the initial request because cyclic dependency TypeA -> TypeB -> TypeA
       * would otherwise publish adapter for TypeB which uses not yet resolved adapter for TypeA
       * See https://github.com/google/gson/issues/625
       */
      typeTokenCache.putAll(threadCalls);
    }
    return candidate;
  }

  /**
   * Returns the type adapter for {@code type}.
   *

View on GitHub (pinned to 8b8628c656)

Solutions

1. Register a TypeAdapter or TypeAdapterFactory for the offending type via GsonBuilder.registerTypeAdapter / registerTypeAdapterFactory.
2. If the class lacks a no-arg constructor, register an InstanceCreator for it.
3. If using JPMS, open the relevant packages to Gson (add-opens JVM flags) or switch to a records-friendly setup.
4. Check reflection filters / excludeFieldsWithModifiers aren't excluding the type entirely.

Example fix

// before: no adapter available, e.g. class without accessible constructor
class NoDefaultCtor { NoDefaultCtor(int x) {} }
Gson gson = new Gson();
String json = gson.toJson(new NoDefaultCtor(1)); // may throw 'cannot handle'

// after: register an InstanceCreator / adapter
class NoDefaultCtorIC implements InstanceCreator<NoDefaultCtor> {
  public NoDefaultCtor createInstance(Type t) { return new NoDefaultCtor(0); }
}
Gson gson = new GsonBuilder().registerTypeAdapter(NoDefaultCtor.class, new NoDefaultCtorIC()).create();

// Probe whether Gson can handle a type before using it
static boolean isHandled(Gson gson, TypeToken<?> type) {
  try {
    return gson.getAdapter(type) != null;
  } catch (IllegalArgumentException e) {
    return false;
  }
}

static <T> boolean hasAdapter(Gson gson, TypeToken<T> type) {
  try { gson.getAdapter(type); return true; }
  catch (IllegalArgumentException e) { return false; }
}

try {
  TypeAdapter<Foo> a = gson.getAdapter(TypeToken.get(Foo.class));
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("cannot handle")) {
    // register an InstanceCreator / TypeAdapter, or open packages for reflection
  } else throw e;
}

When it happens

Trigger: Requesting an adapter for a type Gson inherently cannot handle (e.g. a class with no default constructor and no InstanceCreator, under configurations where reflection is blocked); a type fully excluded by reflection filters; calling getAdapter on an interface with no concrete binding; JDK types not covered by built-in adapters when reflection access is denied on the JPMS classpath.

Common situations: Java modules (JPMS) blocking reflective access to JDK types; classes lacking a no-arg constructor with no InstanceCreator registered; types entirely filtered by excludeFieldsWithModifiers or custom ExclusionStrategy; very old or custom Gson builds missing factories; registering only a TypeAdapterFactory that returns null for everything by mistake.

Related errors

• GSON cannot serialize or deserialize {type}
• Type adapter '{typeAdapter}' returned wrong type; requested
• Adapter for type with cyclic dependency has been used before
• Class {typeAdapter.getClass().getName()} does not implement
• Cannot override built-in adapter for {type}

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