json-path/JsonPath · error · InvalidModificationException

Rename can not be performed to multiple properties

Error message

Rename can not be performed to multiple properties

What it means

Same internal PathRef constraint as the put() case: when a path resolves to multiple properties, the multi-property PathRef cannot rename a single key unambiguously, so renameKey() throws InvalidModificationException. Renaming is only supported on a path that points at exactly one object property.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java:325

        public void delete(Configuration configuration){
            for (String property : properties) {
                configuration.jsonProvider().removeProperty(parent, property);
            }
        }

        @Override
        public void add(Object newVal, Configuration configuration) {
            throw new InvalidModificationException("Add can not be performed to multiple properties");
        }

        @Override
        public void put(String key, Object newVal, Configuration configuration) {
            throw new InvalidModificationException("Put can not be performed to multiple properties");
        }

        @Override
        public void renameKey(String oldKeyName, String newKeyName, Configuration configuration) {
            throw new InvalidModificationException("Rename can not be performed to multiple properties");
        }

        @Override
        public Object getAccessor() {
            return Utils.join("&&", properties);
        }
    }
}

View on GitHub (pinned to 62a4c9f0f6)

Solutions

  1. Iterate over matched objects from read() and rename the key manually on each Map (put new key, remove old key).
  2. Call renameKey once per definite path (e.g. '$.items[0]', '$.items[1]', ...) that resolves to a single property.
  3. Narrow the path with a unique filter/index so exactly one property is matched before renaming.

Example fix

// before
JsonPath.renameKey(json, "$..id", "id", "bookId"); // InvalidModificationException on multi-match
// after
List<Map<String, Object>> items = JsonPath.read(json, "$..items[*]");
for (Map<String, Object> item : items) {
    Object v = item.remove("id");
    item.put("bookId", v);
}
Defensive patterns

Strategy: validation

Validate before calling

Object matched = JsonPath.read(json, path);
if (matched instanceof java.util.List && ((java.util.List<?>) matched).size() != 1) {
    throw new IllegalStateException("renameKey requires a single-property path, got: " + path);
}

Try / catch

try {
    JsonPath.renameKey(json, path, oldKey, newKey);
} catch (InvalidModificationException e) {
    List<Map<String, Object>> items = JsonPath.read(json, path);
    for (Map<String, Object> m : items) { Object v = m.remove(oldKey); if (v != null) m.put(newKey, v); }
}

Prevention

When it happens

Trigger: Calling JsonPath.renameKey(json, path, oldKey, newKey) where the given path matches more than one property (wildcards, deep-scan '$..', or filters resolving to several map entries). PathRef.renameKey with multiple 'properties' throws at PathRef.java:325.

Common situations: Bulk-renaming a field across an array of objects with '$.items[*]' or '$..oldName' paths; works in tests with single objects, fails in production data where the path matches several entries.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of json-path/JsonPath@62a4c9f0f6 (2026-09-11). Data as JSON: /api/errors/f2ef83a8ac8f50e6. Report an issue: GitHub.