apache/incubator-seata · critical · JsonParseException

No JsonCodec provider found. Please add json-common-core to

Error message

No JsonCodec provider found. Please add json-common-core to the runtime classpath.

What it means

JsonCodecFactory.getCodec() lazily loads a JsonCodec implementation via the seata EnhancedServiceLoader SPI. If no provider is discoverable (EnhancedServiceNotFoundException), it throws JsonParseException telling you to add json-common-core to the runtime classpath, because the provider implementation lives in that module.

Source

Thrown at common/src/main/java/org/apache/seata/common/json/JsonCodecFactory.java:47

    private JsonCodecFactory() {}

    /**
     * Get the configured JSON codec provider.
     *
     * @return JSON codec provider
     */
    public static JsonCodec getCodec() {
        JsonCodec result = codec;
        if (result == null) {
            synchronized (JsonCodecFactory.class) {
                result = codec;
                if (result == null) {
                    try {
                        result = EnhancedServiceLoader.load(JsonCodec.class);
                        codec = result;
                    } catch (EnhancedServiceNotFoundException e) {
                        throw new JsonParseException(
                                "No JsonCodec provider found. Please add json-common-core to the runtime classpath.",
                                e);
                    }
                }
            }
        }
        return result;
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Add the seata json-common-core artifact (matching your seata version) to the runtime classpath.
2. If using maven-shade-plugin, add ServicesResourceTransformer so META-INF/services entries survive merging.
3. Verify with: unzip -p yourapp.jar META-INF/services/org.apache.seata.common.json.JsonCodec lists a provider class.
4. Ensure no dependencyMediation downgrades one json module while removing another.

Example fix

<!-- before: only seata-common on classpath -->
<dependency>
  <groupId>org.apache.seata</groupId>
  <artifactId>seata-common</artifactId>
</dependency>

<!-- after: add the codec provider module -->
<dependency>
  <groupId>org.apache.seata</groupId>
  <artifactId>seata-common</artifactId>
</dependency>
<dependency>
  <groupId>org.apache.seata</groupId>
  <artifactId>seata-json-common-core</artifactId>
  <version>${seata.version}</version>
</dependency>

// Fail fast at boot if no JsonCodec provider is registered
boolean codecAvailable =
    EnhancedServiceLoader.load(JsonCodec.class) != null; // wrapped in try/catch
try {
    JsonCodecFactory.getCodec();
} catch (JsonParseException e) {
    throw new IllegalStateException("seata-json-common-core missing from runtime classpath", e);
}

try {
    JsonCodecFactory.getCodec();
} catch (JsonParseException e) {
    if (e.getMessage().contains("No JsonCodec provider")) {
        // add seata-json-common-core dependency and restart; not retryable within same classloader
    }
    throw e;
}

When it happens

Trigger: Calling any seata API that serializes/deserializes JSON (e.g. config parsing, coordinator messages) in a deployment where the seata json-common-core jar (with its META-INF/services entry for JsonCodec) is missing, or the service file was stripped during shading.

Common situations: Slimming seata dependencies and dropping json-common-core; shade plugins merging/dropping META-INF/services; running only seata-common on the classpath; broken fat-jar builds.

Related errors

• No serializer found
• not found service provider for : {} caused by {}
• not found service provider for : {}
• Extension instance(definition: {}, class: {}) could not be
• name value of custom config type must not be blank

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/7ffe01171ddd1d45. Report an issue: GitHub.