apache/hadoop · error · HadoopIllegalArgumentException

unknown scheme for endpoint:{}

Error message

unknown scheme for endpoint:{}

What it means

While constructing listeners, HttpServer2 maps each endpoint URI's scheme to a connector type: 'http' gets a plain ServerConnector, 'https' an SSL connector, and anything else throws HadoopIllegalArgumentException (an IllegalArgumentException) with the full endpoint. A URI with no scheme (null) also fails, since neither branch matches.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/http/HttpServer2.java:586

      server.loadListeners();
      return server;
    }

    @VisibleForTesting
    HttpServer2 addConnectors(
        URI ep, InetAddress[] addresses, HttpServer2 server,
        HttpConfiguration httpConfig, int backlogSize, int idleTimeout){
      for (InetAddress addr : addresses) {
        ServerConnector connector;
        String scheme = ep.getScheme();
        if (HTTP_SCHEME.equals(scheme)) {
          connector = createHttpChannelConnector(
              server.webServer, httpConfig);
        } else if (HTTPS_SCHEME.equals(scheme)) {
          connector = createHttpsChannelConnector(
              server.webServer, httpConfig);
        } else {
          throw new HadoopIllegalArgumentException(
              "unknown scheme for endpoint:" + ep);
        }
        LOG.debug("Adding connector to WebServer for address {}",
            addr.getHostAddress());
        connector.setHost(addr.getHostAddress());
        connector.setPort(ep.getPort() == -1 ? 0 : ep.getPort());
        connector.setAcceptQueueSize(backlogSize);
        connector.setIdleTimeout(idleTimeout);
        server.addListener(connector);
      }
      return server;
    }

    private ServerConnector createHttpChannelConnector(
        Server server, HttpConfiguration httpConfig) {
      ServerConnector conn = new ServerConnector(server,
          conf.getInt(HTTP_ACCEPTOR_COUNT_KEY, HTTP_ACCEPTOR_COUNT_DEFAULT),
          conf.getInt(HTTP_SELECTOR_COUNT_KEY, HTTP_SELECTOR_COUNT_DEFAULT));

View on GitHub (pinned to 2add963021)

Solutions

1. Prefix the endpoint with a scheme the server supports: http://host:port (or https:// when TLS is configured)
2. Check the exact URI being printed in the exception and fix the source property or addEndpoint call
3. If https was intended, ensure the SSL configuration path (ssl-server.xml etc.) is in place so the https branch is usable

Example fix

// before
builder.addEndpoint(URI.create("namenode:9870"));

// after
builder.addEndpoint(URI.create("http://namenode:9870"));

URI ep = URI.create(addr);
String scheme = ep.getScheme() == null ? null : ep.getScheme().toLowerCase(Locale.ROOT);
if (!("http".equals(scheme) || "https".equals(scheme))) {
  throw new ConfigValidationException("endpoint must start with http:// or https://: " + addr);
}
builder.addEndpoint(ep);

try {
  builder.addEndpoint(URI.create(addr));
} catch (HadoopIllegalArgumentException e) {
  // message prints the endpoint: fix the config key that supplied it
  throw new ConfigValidationException("bad web address, need scheme: " + addr, e);
}

When it happens

Trigger: HttpServer2.Builder.addEndpoint(URI.create("host:8088")) with no scheme; a config address like 'hdfs://nn:9870' or 'ftp://...' fed into a web UI address property; a hand-built URI whose scheme string is misspelled ('htp').

Common situations: Custom services embedding HttpServer2 and passing raw host:port strings; configuration migrations where a HA/RPC-style address got copied into a *-http-address / webapp address key.

Related errors

• Problem starting http server
• Bad configuration of hadoop.security.key.provider.path at ${
• Uri without authority: {uri}
• Wrong FS: {path}, expected: {this.getUri()}
• No scheme in default FS: ${uri}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/c722661ad4db438c. Report an issue: GitHub.