{"record":{"id":"d7a4a1bac8e32b88","repo":"json-path/JsonPath","slug":"can-only-add-properties-to-a-map","errorCode":null,"errorMessage":"Can only add properties to a map","messagePattern":"Can only add properties to a map","errorType":"exception","errorClass":"InvalidModificationException","httpStatus":null,"severity":"error","filePath":"json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java","lineNumber":193,"sourceCode":"            if(targetInvalid(target)){\n                return;\n            }\n            if(configuration.jsonProvider().isArray(target)){\n                configuration.jsonProvider().setProperty(target, null, value);\n            } else {\n                throw new InvalidModificationException(\"Can only add to an array\");\n            }\n        }\n\n        public void put(String key, Object value, Configuration configuration){\n            Object target = configuration.jsonProvider().getArrayIndex(parent, index);\n            if(targetInvalid(target)){\n                return;\n            }\n            if(configuration.jsonProvider().isMap(target)){\n                configuration.jsonProvider().setProperty(target, key, value);\n            } else {\n                throw new InvalidModificationException(\"Can only add properties to a map\");\n            }\n        }\n\n        @Override\n        public void renameKey(String oldKeyName, String newKeyName, Configuration configuration) {\n            Object target = configuration.jsonProvider().getArrayIndex(parent, index);\n            if(targetInvalid(target)){\n                return;\n            }\n            renameInMap(target, oldKeyName, newKeyName, configuration);\n        }\n\n        @Override\n        public Object getAccessor() {\n            return index;\n        }\n\n        @Override","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/json-path/JsonPath/blob/62a4c9f0f65ba3f625aa0867d64c528ba72d09ec/json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java#L175-L211","documentation":"PathRef.put() sets a key/value property on the JSON object located by an index-based path. The library only allows put() when the target element is a map; if the element resolved at [parent, index] is an array, scalar, or invalid, put() throws InvalidModificationException(\"Can only add properties to a map\").","triggerScenarios":"Calling JsonPath.parse(...).put(path, key, value) where the index-based path resolves to an element that is not a JSON object — most commonly the element is an array `[...]` and add() was the intended operation.","commonSituations":"Confusing add() and put() semantics when the document shape changed; passing a path to an array element while intending to append; upstream API switched an object field to an array between versions.","solutions":["Verify the target element is a map (jsonProvider().isMap / target instanceof Map) before calling put().","If the target is an array, use add(value) to append instead of put(key, value).","Correct the path so it points at the object that should receive the property.","Catch InvalidModificationException around mutation code when document shapes vary."],"exampleFix":"// before\ncontext.put(\"$.data[0]\", \"status\", \"ok\"); // throws if data[0] is an array\n// after\nObject target = context.read(\"$.data[0]\");\nif (target instanceof Map) {\n    context.put(\"$.data[0]\", \"status\", \"ok\");\n} else {\n    context.add(\"$.data[0]\", \"ok\");\n}","handlingStrategy":"type-guard","validationCode":"Object el = context.read(\"$.data[0]\");\nif (!(el instanceof Map)) throw new IllegalStateException(\"$.data[0] is not a map\");\ncontext.put(\"$.data[0]\", key, value);","typeGuard":"private static boolean isMap(Object o) { return o instanceof Map; }","tryCatchPattern":"try { context.put(path, key, value); } catch (InvalidModificationException e) { log.warn(\"put() target at {} is not a map\", path); }","preventionTips":["Check isMap (instanceof Map) on the resolved element before put().","Remember: arrays take add(), objects take put().","Validate document shape against a schema when the producer may change it.","Handle exceptions when mutating documents from untrusted or versioned sources."],"tags":["json-path","mutation","type-mismatch"],"backgroundTag":"unsupported-operation","analyzedSha":"62a4c9f0f65ba3f625aa0867d64c528ba72d09ec","analyzedAt":"2026-09-11T11:36:00.448Z","contentChangedAt":"2026-09-11T11:36:00.448Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}