hibernate/hibernate-orm · error · HibernateException

Could not find a FormatMapper for the JSON format, which is

Error message

Could not find a FormatMapper for the JSON format, which is required for mapping JSON types. JSON FormatMapper configuration is automatic, but requires that you have either Jackson or a JSONB implementation like Yasson on the class path.

What it means

SessionFactoryOptionsBuilder.getJsonFormatMapper lazily resolves the FormatMapper used to serialize/deserialize JSON-mapped attributes (e.g. @JdbcTypeCode(SqlTypes.JSON)). Resolution is automatic and requires either Jackson (jackson-databind) or a JSON-B implementation such as Yasson (with jakarta.json-api) on the classpath; if neither is found and no explicit hibernate.type.json_format_mapper was configured, this HibernateException is thrown when a JSON attribute needs (de)serialization.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java:1568

	public boolean isPreferJavaTimeJdbcTypesEnabled() {
		return preferJavaTimeJdbcTypes;
	}

	@Override
	public boolean isPreferNativeEnumTypesEnabled() {
		return preferNativeEnumTypes;
	}

	@Override
	public boolean isPreferLocaleLanguageTagEnabled() {
		return preferLocaleLanguageTagEnabled;
	}

	@Override
	@Nonnull
	public FormatMapper getJsonFormatMapper() {
		if ( jsonFormatMapper == null ) {
			throw new HibernateException(
					"Could not find a FormatMapper for the JSON format, which is required for mapping JSON types. JSON FormatMapper configuration is automatic, but requires that you have either Jackson or a JSONB implementation like Yasson on the class path."
			);
		}
		return jsonFormatMapper;
	}

	@Override
	@Nonnull
	public FormatMapper getXmlFormatMapper() {
		if ( xmlFormatMapper == null ) {
			throw new HibernateException(
					"Could not find a FormatMapper for the XML format, which is required for mapping XML types. XML FormatMapper configuration is automatic, but requires that you have either Jackson XML or a JAXB implementation like Glassfish JAXB on the class path."
			);
		}
		return xmlFormatMapper;
	}

	@Override

View on GitHub (pinned to fad1729dce)

Solutions

1. Add Jackson: com.fasterxml.jackson.core:jackson-databind — Hibernate picks it up automatically
2. Or add a JSON-B implementation: org.eclipse:yasson plus jakarta.json:jakarta.json-api
3. Or implement org.hibernate.type.format.FormatMapper and register it via hibernate.type.json_format_mapper=<class> (needs a FormatMapperCreationContext or no-arg constructor)
4. Verify with a bootstrap test that the dependency is really on the runtime classpath, not just the compile one

Example fix

// before: entity with JSON mapping, no JSON library on classpath
@JdbcTypeCode(SqlTypes.JSON)
private Map<String, Object> payload; // -> HibernateException at runtime

// after: build.gradle
dependencies {
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.2'
}

// fail fast at startup if no JSON library is present
static boolean jsonSupportAvailable() {
    return isPresent("com.fasterxml.jackson.databind.ObjectMapper")
        || (isPresent("jakarta.json.bind.Jsonb") && isPresent("jakarta.json.Json"));
}
static boolean isPresent(String cn) {
    try { Class.forName(cn, false, App.class.getClassLoader()); return true; }
    catch (ClassNotFoundException e) { return false; }
}

if (usesJsonMappedAttributes && !jsonSupportAvailable())
    throw new IllegalStateException("Add jackson-databind or yasson: JSON mapping requires one");

try {
    sessionFactory = metadata.buildSessionFactory();
} catch (HibernateException e) {
    if (e.getMessage() != null && e.getMessage().contains("FormatMapper for the JSON format")) {
        // add jackson-databind or yasson to the runtime classpath, or set
        // hibernate.type.json_format_mapper to a custom FormatMapper, then rebuild
    }
    throw e;
}

When it happens

Trigger: An entity maps an attribute as JSON (SqlTypes.JSON / @JdbcTypeCode) but the runtime classpath has neither Jackson nor Yasson/JSON-B, and hibernate.type.json_format_mapper is unset — typically surfacing at SessionFactory bootstrap or first use of the JSON attribute.

Common situations: Slim runtime images (jlink/Quarkus native, minimal Docker layers) that dropped jackson-databind; jakarta.json.bind excluded transitively; switching from a JSON-B to Jackson setup and removing the old dependency without adding jackson-databind; test classpath differs from runtime classpath.

Related errors

• Could not instantiate named strategy class [%s]
• Unable to load class [" + className + "]
• Unsupportd target type
• Unsupportd source type
• Multiple active MetadataBuilder definitions were discovered

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/603d770af82127ff. Report an issue: GitHub.