spring-projects/spring-security · error · IllegalStateException

Cannot find JSON Converter on the classpath. Add one followi

Error message

Cannot find JSON Converter on the classpath. Add one following classes to the classpath tools.jackson.databind.json.JsonMapper, com.fasterxml.jackson.databind.ObjectMapper, tools.jackson.databind.json.JsonMapper, com.google.gson.Gson, jakarta.json.bind.Jsonb

What it means

HttpMessageConverters.getJsonMessageConverter() detects a JSON library on the classpath (Jackson 3 tools.jackson, Jackson 2 ObjectMapper, Gson, or JSON-B) and returns the matching HttpMessageConverter. If none is present it throws IllegalStateException, because JSON-based features (e.g. JSON login) cannot serialize/deserialize without a converter.

Source

Thrown at web/src/main/java/org/springframework/security/web/authentication/HttpMessageConverters.java:83

	/**
	 * Gets the {@link GenericHttpMessageConverterAdapter} to use for JSON.
	 * @return the {@link GenericHttpMessageConverterAdapter} to use.
	 */
	@SuppressWarnings("removal")
	static GenericHttpMessageConverter<Object> getJsonMessageConverter() {
		if (jacksonPresent) {
			return new GenericHttpMessageConverterAdapter<>(new JacksonJsonHttpMessageConverter());
		}
		if (jackson2Present) {
			return new MappingJackson2HttpMessageConverter();
		}
		if (gsonPresent) {
			return new GsonHttpMessageConverter();
		}
		if (jsonbPresent) {
			return new JsonbHttpMessageConverter();
		}
		throw new IllegalStateException(
				"Cannot find JSON Converter on the classpath. Add one following classes to the classpath "
						+ String.join(", ", JSON_MAPPER, OBJECT_MAPPER, JSON_MAPPER, GSON, JSONB));
	}

}

View on GitHub (pinned to 96852e8860)

Solutions

  1. Add a JSON dependency: spring-boot-starter-json (Jackson) or explicit com.fasterxml.jackson.core:jackson-databind, tools.jackson jackson 3, com.google.code.gson:gson, or a JSON-B provider (e.g. Yasson)
  2. If Jackson was excluded to fix conflicts, re-add the correct version instead of removing entirely
  3. Verify with mvn dependency:tree / gradle dependencies that one of the mapper classes is on runtime classpath

Example fix

// before
<exclusions><exclusion>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
</exclusion></exclusions>
// after
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-json</artifactId>
</dependency>
Defensive patterns

Strategy: fallback

Validate before calling

ClassPathPresence:
boolean hasJson = streamOf("tools.jackson.databind.json.JsonMapper",
    "com.fasterxml.jackson.databind.ObjectMapper",
    "com.google.gson.Gson", "jakarta.json.bind.Jsonb").anyMatch(ClassUtils::isPresent);

Type guard

boolean jsonAvailable() {
    return ClassUtils.isPresent("com.fasterxml.jackson.databind.ObjectMapper", getClass().getClassLoader())
        || ClassUtils.isPresent("tools.jackson.databind.json.JsonMapper", getClass().getClassLoader());
}

Try / catch

try {
    converter = HttpMessageConverters.getJsonMessageConverter();
} catch (IllegalStateException e) {
    log.error("No JSON library on classpath — add jackson-databind or gson", e);
    throw e;
}

Prevention

When it happens

Trigger: Using a Spring Security feature that builds default HttpMessageConverters (e.g. a JSON login filter or OAuth2 token endpoint filters) in an application whose classpath contains none of: tools.jackson JsonMapper, com.fasterxml ObjectMapper, Gson, or jakarta.json.bind Jsonb.

Common situations: Minimal/slim Spring Boot apps excluding Jackson (spring-boot-starter-json removed); plain servlet apps using only spring-security-web; dependency exclusions stripping jackson-databind during dependency convergence fixes.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/40b3d5c6bf2f59b4. Report an issue: GitHub.