apache/pulsar · error · IllegalArgumentException

Metadata path must start with '${WELL_KNOWN_PREFIX}', but wa

Error message

Metadata path must start with '${WELL_KNOWN_PREFIX}', but was: ${wellKnownMetadataPath}

What it means

DefaultMetadataResolver.getWellKnownMetadataUrl builds the OIDC discovery URL by appending a well-known metadata path (e.g. /.well-known/openid-configuration) under the issuer URL. If the configured wellKnownMetadataPath does not start with the required WELL_KNOWN_PREFIX ('/.well-known/'), this IllegalArgumentException is thrown. Only spec-conformant discovery paths are supported.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/protocol/DefaultMetadataResolver.java:90

     * @return a URL
     * @see <a href="https://tools.ietf.org/id/draft-ietf-oauth-discovery-08.html#ASConfig">
     * OAuth Discovery: Obtaining Authorization Server Metadata</a>
     */
    public static URL getWellKnownMetadataUrl(URL issuerUrl, String wellKnownMetadataPath) {
        try {
            if (wellKnownMetadataPath == null || wellKnownMetadataPath.isEmpty()) {
                return URI.create(issuerUrl.toExternalForm() + DEFAULT_WELL_KNOWN_METADATA_PATH).normalize().toURL();
            }
            if (wellKnownMetadataPath.startsWith(WELL_KNOWN_PREFIX)) {
                String issuerUrlString = issuerUrl.toExternalForm();
                // For OAuth2, insert well-known path before the issuer URL path
                URL url = new URL(issuerUrlString);
                String path = url.getPath();
                String basePath = issuerUrlString.substring(0,
                        issuerUrlString.length() - (path.isEmpty() ? 0 : path.length()));
                return URI.create(basePath + wellKnownMetadataPath + path).normalize().toURL();
            } else {
                throw new IllegalArgumentException("Metadata path must start with '" + WELL_KNOWN_PREFIX
                        + "', but was: " + wellKnownMetadataPath);
            }
        } catch (MalformedURLException e) {
            throw new IllegalArgumentException(e);
        }
    }

    /**
     * Resolves the authorization metadata.
     *
     * @return metadata
     * @throws IOException if the metadata could not be resolved.
     */
    public Metadata resolve() throws IOException {

        try {
            HttpRequest request = HttpRequest.builder(HttpRequest.Method.GET, URI.create(metadataUrl.toString()))
                    .header("Accept", "application/json")

View on GitHub (pinned to 820761864e)

Solutions

1. Prefix the path with '/.well-known/' (e.g. '/.well-known/openid-configuration' or '/.well-known/oauth-authorization-server').
2. If the IdP is non-standard, keep the standard discovery path or serve metadata at a spec-conformant location.
3. Check the path actually begins with the prefix character-for-character, including the leading slash.

Example fix

// before
new DefaultMetadataResolver(executor).fromIssuerUrl("https://idp.example.com", "openid-configuration"); // throws
// after
new DefaultMetadataResolver(executor).fromIssuerUrl("https://idp.example.com", "/.well-known/openid-configuration");

static void validateWellKnownPath(String p) {
    if (p == null || !p.startsWith("/.well-known/")) {
        throw new IllegalArgumentException("wellKnownMetadataPath must start with '/.well-known/': " + p);
    }
}

boolean isWellKnownPath(String p) {
    return p != null && p.startsWith("/.well-known/");
}

try {
    resolver.fromIssuerUrl(issuerUrl, customMetadataPath);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Metadata path must start with")) {
        throw new ConfigException("Use a '/.well-known/...' discovery path: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: Constructing a DefaultMetadataResolver (via fromIssuerUrl) with a custom wellKnownMetadataPath value that lacks the '/.well-known/' prefix — e.g. 'openid-configuration', '/oauth2/.well-known/...', or a typo like '/.well-known/openid-configuration2' without the leading segment.

Common situations: Customizing the discovery path for a non-standard IdP and forgetting the prefix; typos when overriding defaults; confusing a full token/discovery URL with just the path component.

Related errors

• Cannot obtain authorization metadata from ${metadataUrl}
• earlyTokenRefreshPercent must be greater than 0.
• Required configuration parameters: tlsCertFile, tlsKeyFile
• Unsupported auth method: ${tokenEndpointAuthMethod}
• EarlyTokenRefreshPercent must be greater than 0.

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