{"record":{"id":"0fa9b3e62e6f1169","repo":"hibernate/hibernate-orm","slug":"null-value-passed-to-convert","errorCode":null,"errorMessage":"Null value passed to convert","messagePattern":"Null value passed to convert","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/WrapperArrayHandling.java","lineNumber":61,"sourceCode":"\t * @see CharacterArrayJavaType\n\t *\n\t * @implNote The pre-6.2 behavior\n\t * @apiNote Hibernate recommends users who want the legacy semantic change the domain model to use\n\t * {@code byte[]} and {@code char[]} rather than using this setting.\n\t */\n\tLEGACY,\n\n\t/**\n\t * Hibernate will pick between {@linkplain #ALLOW} and {@linkplain #LEGACY} depending on\n\t * whether the Dialect supports SQL {@code ARRAY} types.\n\t *\n\t * @implNote The default if {@linkplain AvailableSettings#JPA_COMPLIANCE JPA compliance} is enabled.\n\t */\n\tPICK;\n\n\tpublic static WrapperArrayHandling interpretExternalSetting(Object value) {\n\t\tif ( value == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Null value passed to convert\" );\n\t\t}\n\n\t\treturn value instanceof WrapperArrayHandling wrapperArrayHandling\n\t\t\t\t? wrapperArrayHandling\n\t\t\t\t: valueOf( value.toString().toUpperCase( Locale.ROOT ) );\n\t}\n\n\t/**\n\t * Form of {@link #interpretExternalSetting(Object)} which allows incoming {@code null} values and\n\t * simply returns {@code null}.  Useful for chained resolutions\n\t */\n\tpublic static WrapperArrayHandling interpretExternalSettingLeniently(@Nullable Object value) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\treturn value instanceof WrapperArrayHandling wrapperArrayHandling\n\t\t\t\t? wrapperArrayHandling","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/WrapperArrayHandling.java#L43-L79","documentation":"WrapperArrayHandling.interpretExternalSetting(Object) (WrapperArrayHandling.java:56-58) converts the raw value of the hibernate.type.wrapper_array_handling property into the enum, and rejects a null input with IllegalArgumentException 'Null value passed to convert'. 'Null' here means the key was present in the configuration map with a null value (or null was passed programmatically) - an absent key never reaches this method. The lenient sibling interpretExternalSettingLeniently exists for optional resolutions.","triggerScenarios":"Configuration map containing hibernate.type.wrapper_array_handling -> null (e.g. properties.put(key, System.getProperty(key)) where the system property is unset); Spring Environment resolving the key to null but still registering it in JPA properties; custom bootstrap code calling WrapperArrayHandling.interpretExternalSetting(null); spreadsheets/CI variables that define the key with an empty expansion that later becomes null.","commonSituations":"Property files with 'hibernate.type.wrapper_array_handling=' handled as null by a custom loader; conditional configuration code that adds the key whenever a feature flag exists without checking the value; copying settings between environments where one env omits the value; libraries wrapping Hibernate settings that preserve null entries.","solutions":["Remove the null-valued entry from the configuration map so the key is absent rather than null.","In code that reads optional settings, use interpretExternalSettingLeniently(value), which returns null for null input.","Set an explicit valid value: ALLOW, LEGACY, or PICK (uppercase; interpretation uses valueOf on the uppercased string).","Sanitize properties before passing them to EntityManagerFactory setup: drop entries whose value is null."],"exampleFix":"// before\nMap<String, Object> props = new HashMap<>();\nprops.put(\"hibernate.type.wrapper_array_handling\",\n         System.getProperty(\"hibernate.type.wrapper_array_handling\")); // null when unset\n\n// after\nString v = System.getProperty(\"hibernate.type.wrapper_array_handling\");\nif (v != null) {\n    props.put(\"hibernate.type.wrapper_array_handling\", v);\n}","handlingStrategy":"validation","validationCode":"// Strip null-valued Hibernate settings before bootstrap\nprops.entrySet().removeIf(e -> e.getValue() == null);\n// or, when reading optional settings in your own code:\nWrapperArrayHandling h = value == null\n    ? null\n    : WrapperArrayHandling.interpretExternalSettingLeniently(value);","typeGuard":null,"tryCatchPattern":"try {\n    return WrapperArrayHandling.interpretExternalSetting(value);\n} catch (IllegalArgumentException e) {\n    if (\"Null value passed to convert\".equals(e.getMessage())) {\n        return WrapperArrayHandling.PICK; // document this default choice\n    }\n    throw e;\n}","preventionTips":["Never put keys with null values into JPA/Hibernate property maps; absence means default, null means broken.","Prefer interpretExternalSettingLeniently for optional chained setting resolution.","Sanitize environment-derived properties (unset vars) before they reach Hibernate."],"tags":["hibernate","configuration","null-value","wrapper-array-handling","bootstrap"],"backgroundTag":"null-config-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}