{"record":{"id":"fd7002dbce98ccb5","repo":"apache/pulsar","slug":"unable-to-retrieve-oauth-2-0-server-metadata","errorCode":null,"errorMessage":"Unable to retrieve OAuth 2.0 server metadata","messagePattern":"Unable to retrieve OAuth 2\\.0 server metadata","errorType":"exception","errorClass":"PulsarClientException.AuthenticationException","httpStatus":null,"severity":"critical","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/FlowBase.java","lineNumber":251,"sourceCode":"        Duration duration;\n        if (value == null) {\n            log.debug().attr(\"name\", name)\n                    .attr(\"defaultValue\", defaultValue)\n                    .log(\"Configuration is using the default value\");\n            duration = defaultValue;\n        } else {\n            log.debug().attr(\"name\", name).attr(\"value\", value).log(\"Configuration\");\n            duration = value;\n        }\n        return duration;\n    }\n\n    public void initialize() throws PulsarClientException {\n        try {\n            this.metadata = createMetadataResolver().resolve();\n        } catch (IOException e) {\n            log.error().exception(e).log(\"Unable to retrieve OAuth 2.0 server metadata\");\n            throw new PulsarClientException.AuthenticationException(\"Unable to retrieve OAuth 2.0 server metadata\");\n        }\n    }\n\n    protected MetadataResolver createMetadataResolver() {\n        return DefaultMetadataResolver.fromIssuerUrl(issuerUrl, getHttpClient(), wellKnownMetadataPath);\n    }\n\n    static String parseParameterString(Map<String, String> params, String name) {\n        String s = params.get(name);\n        if (StringUtils.isEmpty(s)) {\n            throw new IllegalArgumentException(\"Required configuration parameter: \" + name);\n        }\n        return s;\n    }\n\n    static URL parseParameterUrl(Map<String, String> params, String name) {\n        String s = params.get(name);\n        if (StringUtils.isEmpty(s)) {","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/FlowBase.java#L233-L269","documentation":"FlowBase.initialize() resolves the OAuth2 server metadata (well-known configuration) from the issuerUrl. If the resolver throws IOException, it logs the error and throws AuthenticationException('Unable to retrieve OAuth 2.0 server metadata'). The client could not fetch/discover endpoints like the token endpoint from the IdP.","triggerScenarios":"issuerUrl host unreachable or DNS failure; well-known metadata path (e.g. /.well-known/openid-configuration) returns 404; TLS certificate issues; start() called with no network access.","commonSituations":"Air-gapped or firewalled environments blocking the client from the IdP; wrong issuerUrl (trailing path mistakes, http vs https); self-signed certs not in the truststore; IdP that does not publish standard well-known metadata.","solutions":["Verify issuerUrl is correct and reachable (curl the well-known metadata URL from the client host)","Fix TLS trust (import the IdP certificate into the truststore) if certificate errors occur","Check proxy/firewall rules allowing HTTPS to the issuer host"],"exampleFix":"// before\nauthParams.put(\"issuerUrl\", \"https://auth.example.com/realms/tenant\"); // wrong realm\n// after\nauthParams.put(\"issuerUrl\", \"https://auth.example.com/realms/correct-tenant\");","handlingStrategy":"retry","validationCode":"String wellKnown = issuerUrl.replaceAll(\"/$\", \"\") + \"/.well-known/openid-configuration\";\nHttpURLConnection c = (HttpURLConnection) new java.net.URI(wellKnown).toURL().openConnection();\nc.setConnectTimeout(5000);\nif (c.getResponseCode() != 200) {\n    throw new IllegalStateException(\"IdP metadata not reachable at \" + wellKnown + \": HTTP \" + c.getResponseCode());\n}","typeGuard":null,"tryCatchPattern":"try {\n    flow.initialize();\n} catch (PulsarClientException.AuthenticationException e) {\n    if (e.getMessage().equals(\"Unable to retrieve OAuth 2.0 server metadata\")) {\n        // transient outage: retry with backoff; persistent: check issuerUrl/TLS/proxy\n        retryWithBackoff(() -> flow.initialize());\n    } else throw e;\n}","preventionTips":["Curl the well-known metadata URL from the client host as a preflight","Use https and import the IdP CA cert into the truststore","Confirm firewall/proxy rules allow egress to the issuer host"],"tags":["oauth2","network","metadata","tls"],"backgroundTag":"metadata-resolution-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}