apache/dubbo · error · RuntimeException

Generic serialization [%s] Json syntax exception thrown when

Error message

Generic serialization [%s] Json syntax exception thrown when parsing (message:%s type:%s) error:%s

What it means

Thrown by GsonUtils.fromJson when Gson raises a JsonSyntaxException during deserialization. Dubbo catches it and rethrows as a RuntimeException with a formatted diagnostic including the generic-serialization tag (gson), the offending json payload, the target Type, and Gson's underlying message. The wrapping is unchecked (RuntimeException) so it propagates through generic-invocation call stacks that do not declare checked exceptions. Note: the message says 'parsing' but for fromJson this is deserialization.

Source

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

                        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) {
            throw new RuntimeException(String.format(
                    "Generic serialization [%s] Json syntax exception thrown when parsing (object:%s ) error:%s",
                    GENERIC_SERIALIZATION_GSON, obj, ex.getMessage()));
        }
    }

View on GitHub (pinned to 3a3043227f)

Solutions

Log the full json and type from the exception message, then validate the payload against the expected schema (it usually reveals truncation or a shape change).
Align provider and consumer on the DTO/Type — check for version drift in the generic interface signature.
If the payload may be unreliable, pre-validate with a lenient JSON parser or guard before calling fromJson.
Catch the RuntimeException at the generic-invocation boundary and map it to a domain error rather than letting it bubble as a 500.

Example fix

// before
Object result = GsonUtils.fromJson(payload, MyType.class);
// after - validate + handle
Object result;
try {
    result = GsonUtils.fromJson(payload, MyType.class);
} catch (RuntimeException e) {
    log.error("gson parse failed for payload={}, type={}", payload, MyType.class, e);
    throw new RpcException("Bad JSON payload", e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate JSON structure with a lenient parser or schema before binding.
// At minimum, confirm the payload is non-null and non-empty.
if (json == null || json.isEmpty()) {
    throw new IllegalArgumentException("empty json payload");
}

Try / catch

try {
    return GsonUtils.fromJson(json, type);
} catch (RuntimeException e) {
    // message format: "Generic serialization [gson] Json syntax exception ... (message:%s type:%s) error:%s"
    log.error("gson fromJson failed type={} payload={}", type, json, e);
    throw new RpcException("Invalid JSON payload for type " + type, e);
}

Prevention

Align provider and consumer DTO/Type versions to avoid binding failures.
Log the full payload and target Type from the exception message for triage.
Validate payloads against the expected schema before deserialization when they cross trust boundaries.
Map the RuntimeException to a domain error at the generic-invocation boundary rather than surfacing a raw 500.

When it happens

Trigger: GsonUtils.fromJson(json, type) where json is malformed JSON (unbalanced braces, trailing commas, bad escapes) or is valid JSON that Gson cannot bind to the target Type (e.g. a JSON object where the Type expects an array, unknown fields under a strict policy, or a number where a string is required).

Common situations: Downstream service returns a changed/error response shape; a proxy or filter corrupts the payload (truncation, HTML error page instead of JSON); mismatch between the declared Type and the actual payload (version skew between provider and consumer DTOs); non-UTF-8 bytes decoded incorrectly before reaching Gson; numeric overflow when binding into a narrower field.

Related errors

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