apache/beam · error · IllegalArgumentException

Could not determine port for pubsub root url "%s". You must

Error message

Could not determine port for pubsub root url "%s". You must either specify the port or use the protocol "https" or "http"

What it means

PubsubOptions.targetForRootUrl needs a port to build the gRPC target. If the URL has no explicit port and the protocol is neither https (443) nor http (80), it cannot infer a port and throws IllegalArgumentException telling the user to specify a port or use http/https.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubOptions.java:63

    try {
      url = new URL(urlString);
    } catch (MalformedURLException e) {
      throw new IllegalArgumentException(
          String.format("Could not parse pubsub root url \"%s\"", urlString), e);
    }

    int port = url.getPort();

    if (port < 0) {
      switch (url.getProtocol()) {
        case "https":
          port = 443;
          break;
        case "http":
          port = 80;
          break;
        default:
          throw new IllegalArgumentException(
              String.format(
                  "Could not determine port for pubsub root url \"%s\". You must either specify the port or use the protocol \"https\" or \"http\"",
                  urlString));
      }
    }

    return String.format("%s:%d", url.getHost(), port);
  }

  /** Root URL for use with the Google Cloud Pub/Sub API. */
  @Description("Root URL for use with the Google Cloud Pub/Sub API")
  @Default.String("https://pubsub.googleapis.com")
  @Hidden
  String getPubsubRootUrl();

  void setPubsubRootUrl(String value);
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Include an explicit port in the URL, e.g. 'grpc://localhost:8085' or 'myproto://host:8443'.
2. Use http:// or https:// as the scheme so the default ports (80/443) apply.
3. For the emulator use the standard 'http://localhost:8085'.

Example fix

// before
--pubsubRootUrl=grpc://localhost   // no port, unknown scheme
// after
--pubsubRootUrl=grpc://localhost:8085

java.net.URL u = new java.net.URL(urlString);
if (u.getPort() < 0 && !u.getProtocol().equals("https") && !u.getProtocol().equals("http")) {
  throw new IllegalArgumentException("pubsubRootUrl needs an explicit port or http/https scheme");
}

try {
  options.setPubsubRootUrl(urlString);
} catch (IllegalArgumentException e) {
  // append a port or switch scheme to http/https and retry
}

When it happens

Trigger: Setting pubsubRootUrl to something like 'ftp://host' or 'https://host:0/unknown-scheme://host' — i.e. a scheme other than http/https and no port in the URL.

Common situations: Configuring a custom Pub/Sub endpoint with an exotic scheme, or forgetting the port when pointing at a local emulator with a non-http scheme.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Could not parse pubsub root url "%s"
• Invalid URL: %s
• Need to set either the topic or the subscription for a Pubsu
• Can't set both the topic and the subscription for a PubsubIO
• PubSubIO cannot be configured with both a dead letter topic

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