neo4j/neo4j · error · IllegalArgumentException

'%s' is not a valid name

Error message

'%s' is not a valid name

What it means

Thrown by Name.child(String) in the capabilities API when the proposed child component is blank or contains the '.' namespace separator. Capability names are hierarchical dot-separated paths (e.g. 'db.query.execution'); child() accepts a single segment only, so an empty/whitespace string or a dotted multi-segment argument is rejected with IllegalArgumentException.

Source

Thrown at community/capabilities/src/main/java/org/neo4j/capabilities/Name.java:66

    /**
     * Returns the full name.
     *
     * @return full name.
     */
    public String fullName() {
        return fullName;
    }

    /**
     * Creates a child name from this name instance.
     *
     * @param name child name.
     * @return new name instance.
     * @throws IllegalArgumentException if name is empty or contains '.'.
     */
    public Name child(String name) {
        if (isBlank(name) || contains(name, SEPARATOR)) {
            throw new IllegalArgumentException(String.format("'%s' is not a valid name", name));
        }

        if (isBlank(this.fullName)) {
            return new Name(name);
        }

        return new Name(this.fullName + SEPARATOR + Objects.requireNonNull(name));
    }

    /**
     * Checks if this name instance is in the given namespace.
     *
     * @param namespace namespace to check
     * @return true if this name lies in the given namespace, false otherwise.
     */
    public boolean isIn(String namespace) {
        var validated = validateName(namespace);

View on GitHub (pinned to f213380f81)

Solutions

1. Split fully-qualified names on '.' and chain child() per segment, or use Name.of(fullName) which accepts dotted names
2. Sanitize segments: trim and reject empty parts before calling child()
3. Validate user-supplied names against ^\w+$ before building children

Example fix

// before
Name parent = Name.of("db");
Name n = parent.child("query.execution");

// after
Name n = Name.of("db.query.execution");

String segment = name.trim();
if (segment.isEmpty() || segment.contains(".")) throw new IllegalArgumentException("bad segment");
Name child = parent.child(segment);

private static boolean isValidSegment(String s) { return s != null && !s.isBlank() && !s.contains(".") && s.matches("\\w+"); }

catch (IllegalArgumentException e) { if (e.getMessage().contains("not a valid name")) { split on '.' and chain child() per segment; } else throw e; }

When it happens

Trigger: Calling capabilityName.child("") , child(" "), or child("a.b") — e.g. building a capability tree programmatically from user input or config keys that arrive fully qualified instead of as segments.

Common situations: Constructing capability names from configuration keys that already contain dots; Splitting logic that yields empty segments (trailing dots, double dots) fed straight into child(); Refactors moving from full-name strings to the child() builder without stripping separators

Related errors

• '%s' is not a valid name.
• nested list types is not supported.
• Unsupported queue size %d for thread pool creation.
• Invalid URI provided:
• Invalid tag. Tag must not be empty or null!

AI-assisted analysis of neo4j/neo4j@f213380f81 (2026-08-14). Data as JSON: /api/errors/2ac0ab71d6c21706. Report an issue: GitHub.