alibaba/nacos · critical · NacosLoadException

Jackson 3 is not available on the runtime classpath.

Error message

Jackson 3 is not available on the runtime classpath.

What it means

Thrown by Jackson3JsonAdapter.delegate() when lazy initialization runs and isAvailable() returns false. isAvailable() does Class.forName for the Jackson 3 ObjectMapper and Exception classes; if either is missing from the runtime classpath, the adapter refuses to build a delegate and throws NacosLoadException. This is a hard dependency-resolution failure, not a serialization error.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/json/Jackson3JsonAdapter.java:155

            if (!subtypes.contains(subtype)) {
                subtypes.add(subtype);
            }
            NacosJsonAdapter currentDelegate = delegate;
            if (currentDelegate != null) {
                currentDelegate.registerSubtype(subtype);
            }
        }
    }
    
    private NacosJsonAdapter delegate() {
        NacosJsonAdapter currentDelegate = delegate;
        if (currentDelegate != null) {
            return currentDelegate;
        }
        synchronized (this) {
            if (delegate == null) {
                if (!isAvailable()) {
                    throw new NacosLoadException(
                        "Jackson 3 is not available on the runtime classpath.");
                }
                delegate = createDelegate();
            }
            return delegate;
        }
    }
    
    private NacosJsonAdapter createDelegate() {
        NacosJsonAdapter createdDelegate = new Jackson3JsonAdapterDelegate();
        synchronized (subtypes) {
            for (NacosJsonSubtype subtype : subtypes) {
                createdDelegate.registerSubtype(subtype);
            }
        }
        return createdDelegate;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Add the Jackson 3 dependency to your build (e.g. tools.jackson:jackson-databind and its core) matching the version Nacos expects.
2. If you do not need Jackson 3, switch the configured adapter to Jackson 2 (the default) via the JSON SPI selection instead of forcing JACKSON3.
3. Run with -verbose:class to confirm the Jackson 3 ObjectMapper class is resolvable at runtime.
4. In a fat/shaded jar, verify the shade plugin did not exclude jackson 3 packages and that services entries are preserved.

Example fix

// before — JACKSON3 selected but jars missing
// Nacos loads Jackson3JsonAdapter, isAvailable()==false -> NacosLoadException

// after — Maven adds jackson 3
// <dependency>
//   <groupId>tools.jackson</groupId>
//   <artifactId>jackson-databind</artifactId>
//   <version>3.x</version>
// </dependency>
// OR select the default Jackson 2 adapter instead

if (!adapter.isAvailable()) {
    // fall back to the default Jackson 2 adapter, or fail with a clear message
    throw new IllegalStateException(
        "Jackson 3 not on classpath; add tools.jackson:jackson-databind or switch adapters");
}

boolean jackson3Present(ClassLoader cl) {
    try { Class.forName("tools.jackson.databind.ObjectMapper", false, cl); return true; }
    catch (Throwable t) { return false; }
}

try {
    String json = adapter.toJson(obj);
} catch (NacosLoadException e) {
    // Jackson 3 missing — either add the dependency or select Jackson 2
    log.error("JSON backend unavailable: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Selecting the JACKSON3 adapter (NacosJsonAdapterNames.JACKSON3) and invoking any JSON op when the Jackson 3 jars (tools.jackson.databind ObjectMapper, JacksonException) are not on the classpath; shading/uber-jar builds that excluded jackson 3; running on a runtime where the classes loaded but threw LinkageError/ServiceConfigurationError during Class.forName.

Common situations: App depends on the Nacos client jar which defaults to Jackson 2 but the SPI/config points at Jackson 3 without adding the jackson-3 dependency; a fat jar that deduplicated jackson classes; module path (jigsaw) setup not exporting the jackson 3 module; version conflict where jackson 3 API is present but the databind impl is absent.

Related errors

• 100
• 101
• ASM ClassReader failed to parse class file - probably due to
• {getDescription()} cannot be resolved in the file system for
• {getDescription()} cannot be resolved in the file system for

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/9a1a70b38e56701d. Report an issue: GitHub.