{"record":{"id":"603d770af82127ff","repo":"hibernate/hibernate-orm","slug":"could-not-find-a-formatmapper-for-the-json-format","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java","lineNumber":1568,"sourceCode":"\tpublic boolean isPreferJavaTimeJdbcTypesEnabled() {\n\t\treturn preferJavaTimeJdbcTypes;\n\t}\n\n\t@Override\n\tpublic boolean isPreferNativeEnumTypesEnabled() {\n\t\treturn preferNativeEnumTypes;\n\t}\n\n\t@Override\n\tpublic boolean isPreferLocaleLanguageTagEnabled() {\n\t\treturn preferLocaleLanguageTagEnabled;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic FormatMapper getJsonFormatMapper() {\n\t\tif ( jsonFormatMapper == null ) {\n\t\t\tthrow new HibernateException(\n\t\t\t\t\t\"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.\"\n\t\t\t);\n\t\t}\n\t\treturn jsonFormatMapper;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic FormatMapper getXmlFormatMapper() {\n\t\tif ( xmlFormatMapper == null ) {\n\t\t\tthrow new HibernateException(\n\t\t\t\t\t\"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.\"\n\t\t\t);\n\t\t}\n\t\treturn xmlFormatMapper;\n\t}\n\n\t@Override","sourceCodeStart":1550,"sourceCodeEnd":1586,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java#L1550-L1586","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add Jackson: com.fasterxml.jackson.core:jackson-databind — Hibernate picks it up automatically","Or add a JSON-B implementation: org.eclipse:yasson plus jakarta.json:jakarta.json-api","Or implement org.hibernate.type.format.FormatMapper and register it via hibernate.type.json_format_mapper=<class> (needs a FormatMapperCreationContext or no-arg constructor)","Verify with a bootstrap test that the dependency is really on the runtime classpath, not just the compile one"],"exampleFix":"// before: entity with JSON mapping, no JSON library on classpath\n@JdbcTypeCode(SqlTypes.JSON)\nprivate Map<String, Object> payload; // -> HibernateException at runtime\n\n// after: build.gradle\ndependencies {\n    implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.2'\n}","handlingStrategy":"validation","validationCode":"// fail fast at startup if no JSON library is present\nstatic boolean jsonSupportAvailable() {\n    return isPresent(\"com.fasterxml.jackson.databind.ObjectMapper\")\n        || (isPresent(\"jakarta.json.bind.Jsonb\") && isPresent(\"jakarta.json.Json\"));\n}\nstatic boolean isPresent(String cn) {\n    try { Class.forName(cn, false, App.class.getClassLoader()); return true; }\n    catch (ClassNotFoundException e) { return false; }\n}\n\nif (usesJsonMappedAttributes && !jsonSupportAvailable())\n    throw new IllegalStateException(\"Add jackson-databind or yasson: JSON mapping requires one\");","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = metadata.buildSessionFactory();\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"FormatMapper for the JSON format\")) {\n        // add jackson-databind or yasson to the runtime classpath, or set\n        // hibernate.type.json_format_mapper to a custom FormatMapper, then rebuild\n    }\n    throw e;\n}","preventionTips":["Add jackson-databind (or yasson + jakarta.json-api) explicitly whenever an entity maps JSON attributes","Verify the runtime artifact (Docker image, native build) contains the JSON library, not just the compile classpath","Register a custom FormatMapper via hibernate.type.json_format_mapper when you need a specific ObjectMapper configuration"],"tags":["hibernate","json","format-mapper","classpath","dependency"],"backgroundTag":"missing-classpath-dependency","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}