apache/beam · error · RuntimeException

Expected the endpoint to be of the form

Error message

Expected the endpoint to be of the form <host>:<port> but received {url}

What it means

ExpansionService.waitForAllServicesToBeReady probes each expansion service endpoint by opening a TCP socket to <host>:<port>. To parse the endpoint URL it takes everything after the last ':' as the port; if the URL has no ':' at position > 0 (portIndex <= 0), the endpoint is not in the expected <host>:<port> form and a RuntimeException is thrown.

Solutions

  1. Set the transform service endpoint option to a full host:port value, e.g. localhost:50051.
  2. Check the environment/config that supplies the endpoint for empty or truncated values.
  3. Verify the service was started correctly (the launcher normally registers host:port endpoints).

Example fix

// before
--transformServiceEndpoint=localhost

// after
--transformServiceEndpoint=localhost:50051
Defensive patterns

Strategy: validation

Validate before calling

String url = endpointUrl;
int i = url.lastIndexOf(":");
if (i <= 0 || !url.substring(i + 1).matches("\\d+"))
  throw new IllegalArgumentException("endpoint must be <host>:<port>, got: " + url);

Try / catch

try {
  expansionService.expand(...);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Expected the endpoint"))
    LOG.error("Fix the transform service endpoint option to host:port");
  throw e;
}

Prevention

When it happens

Trigger: Calling expand() or discoverSchemaTransform() when a configured expansion service endpoint's ApiServiceDescriptor URL lacks a host:port form — e.g. an empty URL, a URL with only a port (":1234" gives portIndex==0), or a scheme-less malformed endpoint string.

Common situations: Misconfigured pipeline option for the transform service address (empty string); environment templating leaving the endpoint blank; providing a URL like "localhost" with no port.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/7440daa2d28a202a. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/transform-service/src/main/java/org/apache/beam/sdk/transformservice/ExpansionService.java:80

  }

  // Waits till all expansion services are ready.
  private void waitForAllServicesToBeReady() throws TimeoutException {
    if (disableServiceCheck) {
      // Service check disabled. Just returning.
      return;
    }

    outer:
    for (Endpoints.ApiServiceDescriptor endpoint : endpoints) {
      long start = System.currentTimeMillis();
      long duration = 10;
      while (System.currentTimeMillis() - start < SERVICE_CHECK_TIMEOUT_MILLIS) {
        try {
          String url = endpoint.getUrl();
          int portIndex = url.lastIndexOf(":");
          if (portIndex <= 0) {
            throw new RuntimeException(
                "Expected the endpoint to be of the form <host>:<port> but received " + url);
          }
          int port = Integer.parseInt(url.substring(portIndex + 1));
          String host = url.substring(0, portIndex);
          new Socket(host, port).close();
          // Current service is up. Checking the next one.
          continue outer;
        } catch (IOException exn) {
          try {
            Thread.sleep(duration);
          } catch (InterruptedException e) {
            // Ignore
          }
          duration = (long) (duration * 1.2);
        }
      }
      throw new TimeoutException(
          "Timeout waiting for the service "

View on GitHub (pinned to 12126d8942)