{"record":{"id":"18bb6410f6e70d89","repo":"apache/dubbo","slug":"dubbo-unable-to-find-out-any-json-framework-e-g","errorCode":null,"errorMessage":"Dubbo unable to find out any json framework (e.g. fastjson2, fastjson, gson, jackson) from jvm env. Please import at least one json framework.","messagePattern":"Dubbo unable to find out any json framework \\(e\\.g\\. fastjson2, fastjson, gson, jackson\\) from jvm env\\. Please import at least one json framework\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/utils/JsonUtils.java","lineNumber":72,"sourceCode":"            return jsonUtil;\n        }\n\n        ClassLoader tccl = Thread.currentThread().getContextClassLoader();\n        if (tccl != null && tccl != classLoader) {\n            jsonUtil = loadExtensions(preferName, classLoader, extensions);\n            if (jsonUtil != null) {\n                return jsonUtil;\n            }\n        }\n\n        TreeMap<Integer, JsonUtil> sortedExtensions = new TreeMap<>();\n        for (JsonUtil extension : extensions.values()) {\n            Activate activate = extension.getClass().getAnnotation(Activate.class);\n            sortedExtensions.put(activate == null ? 0 : activate.order(), extension);\n        }\n\n        if (sortedExtensions.isEmpty()) {\n            throw new IllegalStateException(\"Dubbo unable to find out any json framework (e.g. fastjson2, \"\n                    + \"fastjson, gson, jackson) from jvm env. Please import at least one json framework.\");\n        }\n\n        return sortedExtensions.firstEntry().getValue();\n    }\n\n    private static JsonUtil loadExtensions(String name, ClassLoader classLoader, Map<String, JsonUtil> extensions) {\n        ServiceLoader<JsonUtil> loader = ServiceLoader.load(JsonUtil.class, classLoader);\n        Iterator<JsonUtil> it = loader.iterator();\n        // In JDK 21+, ServiceLoader.hasNext() may throw NoClassDefFoundError\n        // when checking class dependencies, so we need to catch it here\n        while (true) {\n            try {\n                if (!it.hasNext()) {\n                    break;\n                }\n                JsonUtil extension = it.next();\n                if (extension.isSupport()) {","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/utils/JsonUtils.java#L54-L90","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a JSON framework dependency; fastjson2 is Dubbo's default (dubbo-serialization-fastjson2 or fastjson2 directly)","Verify the META-INF/services/org.apache.dubbo.common.json.JsonUtil SPI file survives shading (use ServicesResourceTransformer for shade plugin)","Set -Ddubbo.json.framework.prefer-name if multiple frameworks coexist and the wrong one is filtered out"],"exampleFix":"// before: no json dependency\n// after (pom.xml)\n<dependency>\n  <groupId>com.alibaba.fastjson2</groupId>\n  <artifactId>fastjson2</artifactId>\n</dependency>","handlingStrategy":"validation","validationCode":"try {\n    org.apache.dubbo.common.utils.JsonUtils.getJson();\n} catch (IllegalStateException e) {\n    // add fastjson2/gson/jackson dependency, then restart\n}","typeGuard":"static boolean jsonFrameworkPresent() {\n    for (String c : new String[]{\"com.alibaba.fastjson2.JSON\",\"com.google.gson.Gson\",\"com.fasterxml.jackson.databind.ObjectMapper\"})\n        try { Class.forName(c); return true; } catch (ClassNotFoundException ignore) {}\n    return false;\n}","tryCatchPattern":"// 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); }","preventionTips":["Always include dubbo-serialization-fastjson2 (or a JSON lib) in Dubbo deployments","Configure the shade plugin's ServicesResourceTransformer to preserve SPI files"],"tags":["json","serialization","classpath","dependency"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}