apache/beam · error · IllegalArgumentException

Pubsub object name cannot start with goog: {name}

Error message

Pubsub object name cannot start with goog: {name}

What it means

PubsubIO.validatePubsubName rejects any Pub/Sub topic or subscription name that starts with "goog", because Google reserves such names for its own managed topics/subscriptions. This is a fail-fast guard when user code calls PubsubIO.read/write APIs with an invalid resource name.

Source

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

    Matcher match = PROJECT_ID_REGEXP.matcher(project);
    if (!match.matches()) {
      throw new IllegalArgumentException(
          "Illegal project name specified in Pubsub subscription: " + project);
    }
  }

  private static void validatePubsubName(String name) {
    if (name.length() < PUBSUB_NAME_MIN_LENGTH) {
      throw new IllegalArgumentException(
          "Pubsub object name is shorter than 3 characters: " + name);
    }
    if (name.length() > PUBSUB_NAME_MAX_LENGTH) {
      throw new IllegalArgumentException(
          "Pubsub object name is longer than 255 characters: " + name);
    }

    if (name.startsWith("goog")) {
      throw new IllegalArgumentException("Pubsub object name cannot start with goog: " + name);
    }

    Matcher match = PUBSUB_NAME_REGEXP.matcher(name);
    if (!match.matches()) {
      throw new IllegalArgumentException(
          "Illegal Pubsub object name specified: "
              + name
              + " Please see Javadoc for naming rules.");
    }
  }

  /** Populate common {@link DisplayData} between Pubsub source and sink. */
  private static void populateCommonDisplayData(
      DisplayData.Builder builder,
      @Nullable String timestampAttribute,
      @Nullable String idAttribute,
      @Nullable ValueProvider<PubsubTopic> topic) {
    builder

View on GitHub (pinned to 12126d8942)

Solutions

1. Rename the topic/subscription so its name does not start with "goog" (any other prefix is fine, e.g. app-events).
2. If you intend to read a Google-managed goog-* topic, do not reference it by name via PubsubIO name validation paths; use the full resource path and an API that permits it, or subscribe via the Cloud Console-created subscription instead.
3. Check the variable feeding fromTopic/fromSubscription for accidental prefixes from config or templating.

Example fix

// before
PubsubIO.writeStrings().to("projects/my-proj/topics/goog-user-events");
// after
PubsubIO.writeStrings().to("projects/my-proj/topics/user-events");

static boolean validPubsubName(String name) {
  return name != null && name.length() <= 255 && !name.startsWith("goog")
      && name.matches("[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}");
}
// call before: PubsubIO.writeStrings().to("projects/p/topics/" + name);
if (!validPubsubName(name)) throw new IllegalArgumentException("bad pubsub name: " + name);

boolean isSafePubsubName(String name) {
  return name != null && !name.startsWith("goog") && name.matches("[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}");
}

try {
  pipeline.apply(PubsubIO.writeStrings().to(topicPath));
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("cannot start with goog")) {
    throw new ConfigException("Rename topic/subscription; goog* is reserved", e);
  }
  throw e;
}

When it happens

Trigger: Calling PubsubIO.read...().fromTopic()/fromSubscription() or writing with a name whose topic/subscription name component begins with "goog" (e.g. projects/my-proj/topics/goog-my-topic), passing validatePubsubName directly, or building a PubsubMessage to a goog-prefixed destination.

Common situations: Copying Google's own managed topics (e.g. goog-* system topics) as a template for custom topics; typo'd names; testing with names that mimic Google internal naming.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Illegal Pubsub object name specified: {name} Please see Java
• Pipeline update will not be possible because the following t
• Illegal project name specified in Pubsub subscription: {proj
• Pubsub object name is shorter than 3 characters: {name}
• Pubsub object name is longer than 255 characters: {name}

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