apache/pulsar · error · IllegalArgumentException

Illegal syntax: <uri>

Error message

Illegal syntax: <uri>

What it means

URIPreconditions.checkURI validates a URI string against a caller-supplied predicate and throws IllegalArgumentException when the URI either cannot be parsed by java.net.URI (URISyntaxException) or fails the predicate test. Unless a custom errorMessage is provided, the message is "Illegal syntax: <uri>", so the offending string is echoed back to help you spot the malformed part. This is a fail-fast precondition, not a parser: the library assumes callers pass well-formed, predicate-satisfying URIs.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/util/URIPreconditions.java:92

    }

    /**
     * Check whether the given string is a legal URI and passes the user's check.
     *
     * @param uri          URI String
     * @param predicate    User defined rule
     * @param errorMessage Error message
     * @throws IllegalArgumentException Illegal URI or failed in the user's rules
     */
    public static void checkURI(@NonNull String uri,
                                @NonNull Predicate<URI> predicate,
                                @Nullable String errorMessage) throws IllegalArgumentException {
        requireNonNull(uri, "uri");
        requireNonNull(predicate, "predicate");
        try {
            URI u = new URI(uri);
            if (!predicate.test(u)) {
                throw new IllegalArgumentException(errorMessage == null ? "Illegal syntax: " + uri : errorMessage);
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException(errorMessage == null ? "Illegal syntax: " + uri : errorMessage);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Print and inspect the exact string in the message; look for spaces, newlines, quotes, or unencoded characters and remove/encode them.
2. Fix IPv6 literals to a full bracketed form, e.g. http://[::1]:8080 instead of http://[::1.
3. Validate with new java.net.URI(uri) in isolation to see the precise URISyntaxException index/message.
4. If the string parses but fails the predicate, either fix the URI to satisfy it or pass an explicit errorMessage parameter that states the actual requirement.
5. If the input is user/config supplied, trim and normalize (e.g. strip surrounding quotes) before calling checkURI.

Example fix

// before
String url = "pulsar://localhost :6650"; // embedded space
URIPreconditions.checkURI(url, u -> u.getScheme() != null);

// after
String url = "pulsar://localhost:6650";
URIPreconditions.checkURI(url, u -> u.getScheme() != null, "Service URL must have a scheme");

static void validateUri(String uri) {
    if (uri == null || uri.isBlank()) throw new IllegalArgumentException("uri is null/blank");
    try {
        java.net.URI u = new java.net.URI(uri.trim());
        if (u.getScheme() == null) throw new IllegalArgumentException("uri has no scheme: " + uri);
    } catch (java.net.URISyntaxException e) {
        throw new IllegalArgumentException("Bad URI at index " + e.getIndex() + ": " + e.getReason(), e);
    }
}

static boolean isParseableUri(String s) {
    if (s == null) return false;
    try { new java.net.URI(s); return true; } catch (java.net.URISyntaxException e) { return false; }
}

try {
    URIPreconditions.checkURI(uri, predicate);
} catch (IllegalArgumentException e) {
    log.error("Rejected URI '{}': {}", uri, e.getMessage());
    throw new ConfigException("Invalid URI configured: " + uri, e);
}

When it happens

Trigger: Calling URIPreconditions.checkURI(uri, predicate) where (a) the string is not parseable by new java.net.URI(String) — e.g. spaces, unmatched brackets in a host like http://[::1, illegal characters — or (b) the string parses but fails the supplied predicate (e.g. requiring an absolute/hierarchical URI). The same applies via checkURIIfPresent when a non-null value is passed.

Common situations: Broker/ServiceUrl or webServiceUrl config values containing unencoded spaces or copied with surrounding whitespace/quotes; IPv6 literals with a typo (http://[fe80::1); URIs built by string concatenation without URL-encoding; a caller tightening the predicate (e.g. require absolute URIs) while passing relative ones after a version upgrade.

Related errors

• ${key} already exists in the dynamicConfigurationMap
• Topic factory failed to create topic
• No more range can assigned to new consumer, assigned consume
• Range conflict with consumer ${conflictingConsumer}
• Error creating client for HealthChecker

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/77ae2885f00b59e9. Report an issue: GitHub.