{"record":{"id":"b0bb6cd3e35af94c","repo":"hibernate/hibernate-orm","slug":"could-not-determine-how-to-handle-configuration-ra","errorCode":null,"errorMessage":"Could not determine how to handle configuration raw [name=${name}, value=${raw}] as boolean","messagePattern":"Could not determine how to handle configuration raw \\[name=(.+?), value=(.+?)\\] as boolean","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java","lineNumber":126,"sourceCode":"\t */\n\tpublic static boolean getBoolean(String name, Map<?,?> values) {\n\t\treturn getBoolean( name, values, false );\n\t}\n\n\t/**\n\t * Get the config value as a boolean.\n\t *\n\t * @param name The config setting name.\n\t * @param values The map of config values\n\t * @param defaultValue The default value to use if not found\n\t *\n\t * @return The value.\n\t */\n\tpublic static boolean getBoolean(String name, Map<?,?> values, boolean defaultValue) {\n\t\tfinal Object raw = values.get( name );\n\t\tfinal Boolean value = toBoolean( raw, defaultValue );\n\t\tif ( value == null ) {\n\t\t\tthrow new ConfigurationException(\n\t\t\t\t\t\"Could not determine how to handle configuration raw [name=\" + name + \", value=\" + raw + \"] as boolean\"\n\t\t\t);\n\t\t}\n\t\telse {\n\t\t\treturn value;\n\t\t}\n\t}\n\n\tpublic static Boolean toBoolean(Object value, boolean defaultValue) {\n\t\tif ( value == null ) {\n\t\t\treturn defaultValue;\n\t\t}\n\t\telse if (value instanceof Boolean bool) {\n\t\t\treturn bool;\n\t\t}\n\t\telse if (value instanceof String string) {\n\t\t\treturn Boolean.parseBoolean(string);\n\t\t}","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java#L108-L144","documentation":"ConfigurationHelper.getBoolean(name, values, default) resolves a setting from the configuration map. toBoolean accepts exactly three things: null (yields the default), a Boolean, and a String (parsed case-insensitively via Boolean.parseBoolean, which never fails). Any other runtime type — Integer, Long, enum, AtomicBoolean, a custom object — returns null from toBoolean and this method converts that into a ConfigurationException naming the offending setting and raw value.","triggerScenarios":"A configuration map containing a non-Boolean/non-String value for a boolean setting, e.g. props.put(\"hibernate.show_sql\", 1) or an enum/Optional-typed value, when Hibernate (or code calling ConfigurationHelper.getBoolean) reads it during bootstrap.","commonSituations":"Programmatically assembled EntityManagerFactory/SessionFactory property maps with numeric flags (0/1) copied from YAML/env config; typed configuration objects whose getters return int; wrappers that inject boxed types instead of strings; note the exception message gives you the exact property name and value.","solutions":["Read the message: it names the setting and the raw value that failed — fix that map entry first","Store boolean settings only as String (\"true\"/\"false\") or Boolean","Normalize the whole property map before passing it to Hibernate: convert every value to String","Audit YAML/env-to-Properties loaders that map flags to integers"],"exampleFix":"// before\nMap<String, Object> props = new HashMap<>();\nprops.put( \"hibernate.show_sql\", 1 ); // Integer -> ConfigurationException\n// after\nprops.put( \"hibernate.show_sql\", \"true\" );","handlingStrategy":"validation","validationCode":"// Normalize a config map before handing it to Hibernate\nstatic Map<String, Object> normalizeBooleans(Map<String, Object> props, Set<String> booleanKeys) {\n    for ( String key : booleanKeys ) {\n        Object v = props.get( key );\n        if ( v != null && !( v instanceof Boolean ) && !( v instanceof String ) ) {\n            props.put( key, String.valueOf( v ) ); // let Boolean.parseBoolean handle it\n        }\n    }\n    return props;\n}","typeGuard":"static boolean isBooleanConfigValue(Object v) {\n    return v == null || v instanceof Boolean || v instanceof String;\n}","tryCatchPattern":"try {\n    boolean flag = ConfigurationHelper.getBoolean( name, values, false );\n} catch ( ConfigurationException e ) {\n    // message contains name + raw value: normalize that entry and retry bootstrap\n}","preventionTips":["Type all Hibernate properties as String at the configuration source (\"true\"/\"false\")","Beware env-var/YAML bridges that hand over Integer flags like 0/1","Validate the property map once at startup instead of debugging mid-bootstrap failures"],"tags":["hibernate","configuration","type-mismatch","bootstrap","properties"],"backgroundTag":"invalid-configuration-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}