apache/beam · error · IllegalArgumentException

Illegal Pubsub object name specified: {name} Please see Java

Error message

Illegal Pubsub object name specified: {name} Please see Javadoc for naming rules.

What it means

validatePubsubName enforces Cloud Pub/Sub naming rules via PUBSUB_NAME_REGEXP: names must be 3-255 chars, start with a letter, contain only letters, digits, '-', '_', '.', and not start with goog. When the name fails the regex, this error is thrown at pipeline construction time.

Source

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

  }

  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
        .addIfNotNull(
            DisplayData.item("timestampAttribute", timestampAttribute)
                .withLabel("Timestamp Attribute"))
        .addIfNotNull(DisplayData.item("idAttribute", idAttribute).withLabel("ID Attribute"))
        .addIfNotNull(DisplayData.item("topic", topic).withLabel("Pubsub Topic"));

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the name to match [a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}: start with a letter, use only letters/digits/-/_/./~/%/+.
2. Extract and validate only the name component if you mistakenly passed the full projects/.../topics/... path where a bare name is expected.
3. Pre-validate names with the same regex before calling the PubsubIO builder.

Example fix

// before
String topic = "my topic!"; // invalid chars
PubsubIO.writeStrings().to("projects/p/topics/" + topic);
// after
String topic = "my-topic";
if (!topic.matches("[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}")) throw new IllegalArgumentException(topic);
PubsubIO.writeStrings().to("projects/p/topics/" + topic);

private static final Pattern NAME = Pattern.compile("[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}");
static void checkName(String name) {
  if (name == null || !NAME.matcher(name).matches())
    throw new IllegalArgumentException("Invalid Pub/Sub name: " + name);
}

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

try {
  return PubsubIO.readStrings().fromSubscription(path);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Illegal Pubsub object name"))
    throw new ConfigException("Name violates Pub/Sub naming rules: " + path, e);
  throw e;
}

When it happens

Trigger: Passing a topic/subscription name containing illegal characters (spaces, slashes, '!', uppercase is allowed but symbols like ':' are not), a name shorter than 3 characters, or a name starting with a digit/symbol to fromTopic/fromSubscription or PubsubMessage creation.

Common situations: Interpolating user input or environment-specific values into topic names; using full paths where only the name is expected in a template; legacy names from other systems with invalid characters.

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

• Pubsub object name cannot start with goog: {name}
• 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/054d2866311b3687. Report an issue: GitHub.