{"record":{"id":"51b2402bed4cfbe1","repo":"json-path/JsonPath","slug":"invalid-add-operation-is-not-an-array","errorCode":null,"errorMessage":"Invalid add operation. $ is not an array","messagePattern":"Invalid add operation\\. \\$ is not an array","errorType":"exception","errorClass":"InvalidModificationException","httpStatus":null,"severity":"error","filePath":"json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java","lineNumber":127,"sourceCode":"        public void set(Object newVal, Configuration configuration) {\n            throw new InvalidModificationException(\"Invalid set operation\");\n        }\n\n        public void convert(MapFunction mapFunction, Configuration configuration){\n            throw new InvalidModificationException(\"Invalid map operation\");\n        }\n\n        @Override\n        public void delete(Configuration configuration) {\n            throw new InvalidModificationException(\"Invalid delete operation\");\n        }\n\n        @Override\n        public void add(Object newVal, Configuration configuration) {\n            if(configuration.jsonProvider().isArray(parent)){\n                configuration.jsonProvider().setArrayIndex(parent, configuration.jsonProvider().length(parent), newVal);\n            } else {\n                throw new InvalidModificationException(\"Invalid add operation. $ is not an array\");\n            }\n        }\n\n        @Override\n        public void put(String key, Object newVal, Configuration configuration) {\n            if(configuration.jsonProvider().isMap(parent)){\n                configuration.jsonProvider().setProperty(parent, key, newVal);\n            } else {\n                throw new InvalidModificationException(\"Invalid put operation. $ is not a map\");\n            }\n        }\n\n        @Override\n        public void renameKey(String oldKeyName, String newKeyName, Configuration configuration) {\n            Object target = parent;\n            if(targetInvalid(target)){\n                return;\n            }","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/json-path/JsonPath/blob/62a4c9f0f65ba3f625aa0867d64c528ba72d09ec/json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java#L109-L145","documentation":"The root ('$') PathRef.add appends a value to the root only when the root is an array. If the root document is a JSON object (or scalar), there is nothing to append to, so it throws InvalidModificationException 'Invalid add operation. $ is not an array'.","triggerScenarios":"Calling JsonPath.add(document, \"$\", newVal, configuration) where the parsed root is a JSON object, e.g. trying to append to a document whose top level is an object like {\"items\": [...]}.","commonSituations":"Assuming the document root is an array while the API returns an object wrapper; appending to the wrong level — the intended array is at \"$.items\", not at the root; documents whose shape differs across environments.","solutions":["Target the actual array path, e.g. JsonPath.add(document, \"$.items\", newVal, conf).","Check isArray on the root (configuration.jsonProvider().isArray(root)) before adding.","If the root is a map and you want a new key, use put with an explicit key instead of add.","Unwrap the document first if the producer nests your array under a known key."],"exampleFix":"// before\nJsonPath.add(document, \"$\", newItem, conf); // root is an object\n// after\nJsonPath.add(document, \"$.items\", newItem, conf);","handlingStrategy":"type-guard","validationCode":"Object root = JsonPath.parse(document).json();\nif (!(root instanceof List)) {\n    throw new IllegalArgumentException(\"Root is not an array; use put on a nested object path or add on $.items\");\n}","typeGuard":"boolean rootIsArray(Object doc, Configuration conf) {\n    Object root = JsonPath.parse(doc, conf).json();\n    return conf.jsonProvider().isArray(root);\n}","tryCatchPattern":"try {\n    JsonPath.add(document, \"$\", newVal, conf);\n} catch (InvalidModificationException e) {\n    // root is not an array: fall back to the known array path\n    JsonPath.add(document, \"$.items\", newVal, conf);\n}","preventionTips":["Inspect the document root shape before choosing add vs put","Target the actual array property (e.g. $.items), not \"$\"","Validate API response shape before mutating — roots vary across endpoints","Prefer explicit nested paths over assuming the root type"],"tags":["json-path","add-operation","root-path","array"],"backgroundTag":"type-mismatch","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"}