elastic/elasticsearch · error · IllegalArgumentException

pathPrefix must not be empty

Error message

pathPrefix must not be empty

What it means

Validation in cleanPathPrefix: a non-null pathPrefix is required and must be non-empty. An empty string is rejected (separately from the null check) because it would silently produce ambiguous URIs.

Source

Thrown at client/rest/src/main/java/org/elasticsearch/client/RestClientBuilder.java:216

     * For example, if this is set to "/my/path", then any client request will become <code>"/my/path/" + endpoint</code>.
     * <p>
     * In essence, every request's {@code endpoint} is prefixed by this {@code pathPrefix}. The path prefix is useful for when
     * Elasticsearch is behind a proxy that provides a base path or a proxy that requires all paths to start with '/';
     * it is not intended for other purposes and it should not be supplied in other scenarios.
     *
     * @throws NullPointerException if {@code pathPrefix} is {@code null}.
     * @throws IllegalArgumentException if {@code pathPrefix} is empty or contains consecutive slashes.
     */
    public RestClientBuilder setPathPrefix(String pathPrefix) {
        this.pathPrefix = cleanPathPrefix(pathPrefix);
        return this;
    }

    public static String cleanPathPrefix(String pathPrefix) {
        Objects.requireNonNull(pathPrefix, "pathPrefix must not be null");

        if (pathPrefix.isEmpty()) {
            throw new IllegalArgumentException("pathPrefix must not be empty");
        }

        if (pathPrefix.contains("//")) {
            throw new IllegalArgumentException("pathPrefix is malformed. consecutive slashes are not allowed: [" + pathPrefix + "]");
        }

        String cleanPathPrefix = pathPrefix;
        if (cleanPathPrefix.startsWith("/") == false) {
            cleanPathPrefix = "/" + cleanPathPrefix;
        }

        // best effort to ensure that it looks like "/base/path" rather than "/base/path/"
        if (cleanPathPrefix.endsWith("/") && cleanPathPrefix.length() > 1) {
            cleanPathPrefix = cleanPathPrefix.substring(0, cleanPathPrefix.length() - 1);
        }
        return cleanPathPrefix;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Only call setPathPrefix when the value is non-empty; skip the call entirely to keep the default (no prefix).
2. Trim and validate the prefix before passing: if (prefix != null && !prefix.isBlank()) builder.setPathPrefix(prefix.trim()).
3. Treat empty prefix as 'no prefix', not as an error.

Example fix

// before
builder.setPathPrefix(config.get("pathPrefix", "")); // empty -> throws
// after
String prefix = config.get("pathPrefix", "");
if (prefix != null && !prefix.isBlank()) builder.setPathPrefix(prefix.trim());

String p = prefix == null ? null : prefix.trim();
if (p != null && !p.isEmpty()) builder.setPathPrefix(p);

When it happens

Trigger: Calling RestClient.builder(...).setPathPrefix("") after trimming user input that became empty.

Common situations: Config supplied a whitespace-only prefix that was trimmed to empty; conditional code calling setPathPrefix(prefix) without checking it was set; default-empty field concatenated into the builder.

Related errors

• pathPrefix is malformed. consecutive slashes are not allowed
• hosts must not be null nor empty
• nodes must not be null or empty
• node cannot be null
• can't compare DeadHostStates holding different time supplier

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/637aa8f79e06c481. Report an issue: GitHub.