apache/beam · error · IllegalArgumentException

Could not parse pubsub root url

Error message

Could not parse pubsub root url "%s"

What it means

PubsubOptions.targetForRootUrl converts a custom Pub/Sub root URL into a host[:port] target for the gRPC channel. If the URL string cannot be parsed by java.net.URL (MalformedURLException), it throws IllegalArgumentException with this message and the cause.

Solutions

1. Fix the pubsubRootUrl value to be a well-formed absolute URL, e.g. 'https://pubsub.googleapis.com' or 'http://localhost:8085'.
2. Validate the URL with new URL(...) or a regex before setting the option.
3. Check the config file/flag for stray characters, spaces, or unescaped quotes.

Example fix

// before
--pubsubRootUrl=localhost:8085   // may be rejected depending on parse
// after
--pubsubRootUrl=http://localhost:8085

try { new java.net.URL(urlString); } catch (java.net.MalformedURLException e) {
  throw new IllegalArgumentException("pubsubRootUrl must be an absolute URL like http://localhost:8085", e);
}

try {
  options.setPubsubRootUrl(urlString);
} catch (IllegalArgumentException e) {
  log.error("Bad pubsubRootUrl: {}", urlString, e);
}

When it happens

Trigger: Setting the pubsubRootUrl option/property to a malformed string, e.g. missing scheme ('localhost:8085' is fine, but 'localhost//' or '::bad::' is not) or containing invalid characters.

Common situations: Pointing at a local emulator or mock server and typos in the URL, quoting mistakes in config files, or missing the scheme entirely in ways java.net.URL rejects.

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

• Could not determine port for pubsub root url
• A schema was provided without a data format (or viceversa)…
• Can't set both the topic and the subscription for a…
• Configuration schema provided does not match expected
• Dead letter queue topic name is not specified

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

Appendix: source

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

/** Properties that can be set when using Google Cloud Pub/Sub with the Apache Beam SDK. */
@Description(
    "Options that are used to configure Google Cloud Pub/Sub. See "
        + "https://cloud.google.com/pubsub/docs/overview for details on Cloud Pub/Sub.")
public interface PubsubOptions
    extends ApplicationNameOptions, GcpOptions, PipelineOptions, StreamingOptions {

  /**
   * Internal only utility for converting {@link #getPubsubRootUrl()} (e.g. {@code https://<host>})
   * to an endpoint target, usable by GCP client libraries (e.g. {@code <host>:443})
   */
  @Internal
  static String targetForRootUrl(String urlString) {
    URL url;
    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));

View on GitHub (pinned to 12126d8942)