{"record":{"id":"6d42f2ecfbf5a881","repo":"apache/pulsar","slug":"field-name-must-be-a-map","errorCode":null,"errorMessage":"Field ${name} must be a Map","messagePattern":"Field (.+?) must be a Map","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-config-validation/src/main/java/org/apache/pulsar/config/validation/ConfigValidationUtils.java","lineNumber":140,"sourceCode":"            @SuppressWarnings(\"unchecked\")\n            @Override\n            public void validateField(String pd, String name, Object field)\n                    throws IllegalArgumentException {\n                if (field == null) {\n                    if (notNull) {\n                        throw new IllegalArgumentException(\"Field \" + name + \" must not be null\");\n                    } else {\n                        return;\n                    }\n                }\n                if (field instanceof Map) {\n                    for (Map.Entry<Object, Object> entry : ((Map<Object, Object>) field).entrySet()) {\n                        key.validateField(\"Each key of the map \", name, entry.getKey());\n                        val.validateField(\"Each value in the map \", name, entry.getValue());\n                    }\n                    return;\n                }\n                throw new IllegalArgumentException(\n                        \"Field \" + name + \" must be a Map\");\n            }\n        };\n    }\n\n    /**\n     * Declares methods for validating configuration values.\n     */\n    public interface FieldValidator {\n        /**\n         * Validates the given field.\n         *\n         * @param name  the name of the field.\n         * @param field The field to be validated.\n         * @throws IllegalArgumentException if the field fails validation.\n         */\n        void validateField(String name, Object field) throws IllegalArgumentException;\n    }","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-config-validation/src/main/java/org/apache/pulsar/config/validation/ConfigValidationUtils.java#L122-L158","documentation":"The map-validator NestableFieldValidator throws IllegalArgumentException when the field is non-null but not a java.util.Map, indicating a map-typed config field was given some other object (list, string, etc.).","triggerScenarios":"A map-typed config property assigned a List, String, or other non-Map value before ConfigValidation runs validateField.","commonSituations":"YAML written as a dash list where a mapping (key: value) is required; JSON array supplied for an object field; programmatic assignment of a List where Map<String,String> is declared.","solutions":["Rewrite the value as a mapping (YAML 'key: value' pairs / JSON object)","Fix programmatic construction to assign a Map type matching the field declaration","Check the validator's declared key/value validators to ensure entries conform once it is a Map"],"exampleFix":"# before (list instead of map)\noptions:\n  - a=1\n# after\noptions:\n  a: \"1\"","handlingStrategy":"type-guard","validationCode":"// before validateConfig\nObject options = conf.get(\"options\");\nif (!(options instanceof java.util.Map)) throw new IllegalStateException(\"options must be a key/value map\");","typeGuard":"static boolean isMap(Object o) { return o instanceof java.util.Map; }","tryCatchPattern":"try {\n    ConfigValidation.validateConfig(conf);\n} catch (IllegalArgumentException e) {\n    throw new IllegalStateException(\"Map field given non-map value: \" + e.getMessage(), e);\n}","preventionTips":["Use YAML mappings (key: value), not dash lists, for map fields","Use JSON objects ({}), not arrays, for map-typed settings","Keep programmatic assignment typed to the declared Map type"],"tags":["config-validation","type-mismatch","map"],"backgroundTag":"config-type-mismatch","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}