apache/dubbo · error · IllegalStateException

Dubbo unable to find out any json framework (e.g. fastjson2,

Error message

Dubbo unable to find out any json framework (e.g. fastjson2, fastjson, gson, jackson) from jvm env. Please import at least one json framework.

What it means

JsonUtils.createJsonUtil scans ServiceLoader providers of JsonUtil (fastjson2, fastjson, gson, jackson adapters). If none is present and supported on the classpath, Dubbo has no JSON backend and throws IllegalStateException. JSON is required for metadata exchange, generic invocation, and some serialization paths.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/utils/JsonUtils.java:72

            return jsonUtil;
        }

        ClassLoader tccl = Thread.currentThread().getContextClassLoader();
        if (tccl != null && tccl != classLoader) {
            jsonUtil = loadExtensions(preferName, classLoader, extensions);
            if (jsonUtil != null) {
                return jsonUtil;
            }
        }

        TreeMap<Integer, JsonUtil> sortedExtensions = new TreeMap<>();
        for (JsonUtil extension : extensions.values()) {
            Activate activate = extension.getClass().getAnnotation(Activate.class);
            sortedExtensions.put(activate == null ? 0 : activate.order(), extension);
        }

        if (sortedExtensions.isEmpty()) {
            throw new IllegalStateException("Dubbo unable to find out any json framework (e.g. fastjson2, "
                    + "fastjson, gson, jackson) from jvm env. Please import at least one json framework.");
        }

        return sortedExtensions.firstEntry().getValue();
    }

    private static JsonUtil loadExtensions(String name, ClassLoader classLoader, Map<String, JsonUtil> extensions) {
        ServiceLoader<JsonUtil> loader = ServiceLoader.load(JsonUtil.class, classLoader);
        Iterator<JsonUtil> it = loader.iterator();
        // In JDK 21+, ServiceLoader.hasNext() may throw NoClassDefFoundError
        // when checking class dependencies, so we need to catch it here
        while (true) {
            try {
                if (!it.hasNext()) {
                    break;
                }
                JsonUtil extension = it.next();
                if (extension.isSupport()) {

View on GitHub (pinned to 3a3043227f)

Solutions

1. Add a JSON framework dependency; fastjson2 is Dubbo's default (dubbo-serialization-fastjson2 or fastjson2 directly)
2. Verify the META-INF/services/org.apache.dubbo.common.json.JsonUtil SPI file survives shading (use ServicesResourceTransformer for shade plugin)
3. Set -Ddubbo.json.framework.prefer-name if multiple frameworks coexist and the wrong one is filtered out

Example fix

// before: no json dependency
// after (pom.xml)
<dependency>
  <groupId>com.alibaba.fastjson2</groupId>
  <artifactId>fastjson2</artifactId>
</dependency>

try {
    org.apache.dubbo.common.utils.JsonUtils.getJson();
} catch (IllegalStateException e) {
    // add fastjson2/gson/jackson dependency, then restart
}

static boolean jsonFrameworkPresent() {
    for (String c : new String[]{"com.alibaba.fastjson2.JSON","com.google.gson.Gson","com.fasterxml.jackson.databind.ObjectMapper"})
        try { Class.forName(c); return true; } catch (ClassNotFoundException ignore) {}
    return false;
}

// Error fires at startup; catch at bootstrap and fail fast with a clear dependency hint. try { JsonUtils.getJson(); } catch (IllegalStateException e) { throw new IllegalStateException("Add fastjson2/gson/jackson to classpath", e); }

When it happens

Trigger: Application starts and any code path (metadata, generic call, REST, configuration) calls JsonUtils.getJson() when no JSON framework JAR is on the classpath, or when every provider's isSupport() returned false.

Common situations: Minimal Dubbo deployment that excluded the default fastjson2 dependency; dependency shading that dropped the META-INF/services JsonUtil SPI file; classpath isolation where the JSON JAR is in a parent loader not visible to Dubbo's loader.

Related errors

• Generic serialization [%s] Json syntax exception thrown when
• unsupported route engine type: {type}
• type [ ${type} ] is unsupported
• ${cause.message}
• Unsupported type ${className}:${type}

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