{"record":{"id":"ee7baacfa3bd68c6","repo":"hibernate/hibernate-orm","slug":"unrecognized-flush-mode-name","errorCode":null,"errorMessage":"Unrecognized flush mode : ${name}","messagePattern":"Unrecognized flush mode : (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/internal/FlushModeMarshalling.java","lineNumber":43,"sourceCode":"\t\t// Also, we want to map \"never\"->MANUAL (rather than NEVER)\n\t\tif ( name == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif ( \"never\".equalsIgnoreCase( name ) ) {\n\t\t\treturn FlushMode.MANUAL;\n\t\t}\n\t\telse if ( \"auto\".equalsIgnoreCase( name ) ) {\n\t\t\treturn FlushMode.AUTO;\n\t\t}\n\t\telse if ( \"always\".equalsIgnoreCase( name ) ) {\n\t\t\treturn FlushMode.ALWAYS;\n\t\t}\n\n\t\t// if the incoming value was not null *and* was not one of the pre-defined\n\t\t// values, we need to throw an exception.  This *should never happen if the\n\t\t// document we are processing conforms to the schema...\n\t\tthrow new HibernateException( \"Unrecognized flush mode : \" + name );\n\t}\n\n\tpublic static String toXml(FlushMode mode) {\n\t\tif ( mode == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\t// conversely, we want to map MANUAL -> \"never\" here\n\t\tif ( mode == FlushMode.MANUAL ) {\n\t\t\treturn \"never\";\n\t\t}\n\n\t\t// todo : what to do if the incoming value does not conform to allowed values?\n\t\t// for now, we simply don't deal with that (we write it out).\n\n\t\treturn mode.name().toLowerCase( Locale.ENGLISH );\n\t}\n}","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/internal/FlushModeMarshalling.java#L25-L61","documentation":"FlushModeMarshalling.fromXml accepts exactly three tokens case-insensitively: 'never' (mapped to FlushMode.MANUAL), 'auto', and 'always'. Any other non-null string — including otherwise valid enum names like 'commit' or 'manual' — throws HibernateException('Unrecognized flush mode : name'). The comment in code notes this should never occur in schema-valid documents, because the XSD restricts the attribute values.","triggerScenarios":"A flush-mode attribute in an hbm.xml (e.g. <query flush-mode=\"...\">) or mapping document containing a token outside {never, auto, always}: 'commit', 'manual', 'automatic', or a typo — possible when schema validation was skipped, the document was hand-built, or a custom XSD relaxed the enumeration.","commonSituations":"Developers copying FlushMode.COMMIT's enum name into XML; tooling generating mappings from annotations without mapping enum names to the XML vocabulary; hand-written XML that was never schema-validated.","solutions":["Change the XML value to one of 'never', 'auto', or 'always' (these are the only XML-legal tokens)","If you need COMMIT semantics, configure the flush mode programmatically on the Session/Query instead of in XML","Validate all mapping documents against Hibernate's bundled XSD in CI so out-of-vocabulary values fail early with a precise location"],"exampleFix":"<!-- before -->\n<query name=\"Item.bySku\" flush-mode=\"commit\">...</query>\n\n<!-- after -->\n<query name=\"Item.bySku\" flush-mode=\"always\">...</query>","handlingStrategy":"validation","validationCode":"private static final Set<String> XML_FLUSH_MODES = Set.of(\"never\", \"auto\", \"always\");\nString value = attrValue.toLowerCase(java.util.Locale.ROOT);\nif (!XML_FLUSH_MODES.contains(value)) {\n    throw new IllegalArgumentException(\"flush-mode must be one of \" + XML_FLUSH_MODES + \": \" + value);\n}","typeGuard":null,"tryCatchPattern":"catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unrecognized flush mode\")) {\n        throw new IllegalArgumentException(\"XML flush-mode must be never|auto|always\", e);\n    }\n    throw e;\n}","preventionTips":["Remember XML vocabulary differs from FlushMode enum names (COMMIT/MANUAL are not legal in XML)","Validate mapping files against the bundled XSD in CI","Set COMMIT flush mode programmatically on Session/Query, never via XML"],"tags":["xml","flush-mode","mapping-file","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}