apache/dubbo · critical · RuntimeException

Gson is not supported. Please import Gson in JVM env.

Error message

Gson is not supported. Please import Gson in JVM env.

What it means

Thrown by GsonUtils.fromJson(String, Type) when isSupportGson() returns false — i.e. the class com.google.gson.Gson could not be loaded via ClassUtils.forName on the runtime classpath. GsonUtils is a thin static facade over Gson used by Dubbo's generic invocation (generic serialization = gson). Unlike the JSON-parsing exceptions, this is a missing-dependency error: Gson (com.google.gson:gson) is absent from the JVM env.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/json/GsonUtils.java:53

    private static boolean isSupportGson() {
        if (supportGson == null) {
            synchronized (GsonUtils.class) {
                if (supportGson == null) {
                    try {
                        Class<?> aClass = ClassUtils.forName("com.google.gson.Gson");
                        supportGson = aClass != null;
                    } catch (Throwable t) {
                        supportGson = false;
                    }
                }
            }
        }
        return supportGson;
    }

    public static Object fromJson(String json, Type originType) throws RuntimeException {
        if (!isSupportGson()) {
            throw new RuntimeException("Gson is not supported. Please import Gson in JVM env.");
        }
        Type type = TypeToken.get(originType).getType();
        try {
            return getGson().fromJson(json, type);
        } catch (JsonSyntaxException ex) {
            throw new RuntimeException(String.format(
                    "Generic serialization [%s] Json syntax exception thrown when parsing (message:%s type:%s) error:%s",
                    GENERIC_SERIALIZATION_GSON, json, type.toString(), ex.getMessage()));
        }
    }

    public static String toJson(Object obj) throws RuntimeException {
        if (!isSupportGson()) {
            throw new RuntimeException("Gson is not supported. Please import Gson in JVM env.");
        }
        try {
            return getGson().toJson(obj);
        } catch (JsonSyntaxException ex) {

View on GitHub (pinned to 3a3043227f)

Solutions

Add the Gson dependency to your build/runtime, e.g. Maven: <dependency><groupId>com.google.gson</groupId><artifactId>gson</artifactId></dependency> matching the version Dubbo expects.
If you shaded/excluded gson intentionally, switch the generic serialization away from gson (use a different generic serialization).
Verify the gson jar is actually on the application classloader at runtime (not just compile scope) — check for provided/optional scoping that drops it at runtime.
In a multi-classloader env, ensure Gson loads from the same loader Dubbo uses for ClassUtils.forName.

Example fix

// pom.xml before: gson excluded
// after: add the dependency
<dependency>
  <groupId>com.google.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.10.1</version>
</dependency>

Defensive patterns

Strategy: try-catch

Validate before calling

// Fail fast at startup by probing Gson availability via the same path Dubbo uses.
boolean gsonPresent;
try {
    Class.forName("com.google.gson.Gson");
    gsonPresent = true;
} catch (ClassNotFoundException e) {
    gsonPresent = false;
}
if (!gsonPresent) {
    throw new IllegalStateException("gson dependency missing; add com.google.gson:gson to the runtime classpath");
}

Try / catch

try {
    return GsonUtils.fromJson(json, type);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Gson is not supported")) {
        throw new IllegalStateException("gson dependency missing on classpath", e);
    }
    throw e;
}

Prevention

Declare the gson dependency at runtime scope, not optional/provided, when using serialization=gson.
In multi-classloader environments, ensure Gson loads from the same loader Dubbo's ClassUtils.forName uses.
Probe Gson availability at startup and fail fast with an actionable message.
If Gson is intentionally excluded, switch the generic serialization to a different strategy.

When it happens

Trigger: Calling GsonUtils.fromJson(json, type) on a runtime where the gson jar is not present. isSupportGson() is cached after first check; once it resolves to false it stays false for the JVM lifetime (only resettable via the @Deprecated setSupportGson test hook).

Common situations: Slimmed Dubbo distribution or shaded uber-jar that excluded the gson dependency; classloader isolation (OSGi, Tomcat, custom plugin loader) where Gson is on a parent/peer loader Dubbo cannot reach via forName; using Dubbo generic invocation with serialization=gson without declaring the gson artifact; partial upgrade where an old gson was shaded out.

Related errors

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/e3ad4df6229669e2. Report an issue: GitHub.