apache/beam · error · IllegalArgumentException

Pubsub object name is longer than 255 characters: {name}

Error message

Pubsub object name is longer than 255 characters: {name}

What it means

Pub/Sub resource names may be at most 255 characters (PUBSUB_NAME_MAX_LENGTH). validatePubsubName rejects names longer than this with an IllegalArgumentException so the invalid name never reaches the service.

Source

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

  public static final String ENABLE_CUSTOM_PUBSUB_SINK = "enable_custom_pubsub_sink";
  public static final String ENABLE_CUSTOM_PUBSUB_SOURCE = "enable_custom_pubsub_source";

  private static void validateProjectName(String project) {
    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(

View on GitHub (pinned to 12126d8942)

Solutions

1. Shorten the name to 255 characters or fewer, keeping the meaningful suffix
2. Pass only the bare resource name, not the full path
3. Bound generated names (hash or truncate UUID/timestamp components)
4. Validate name length before submitting the pipeline

Example fix

// before
String name = "projects/p/topics/" + topic; // passed to PubsubIO
// after
PubsubIO.writeStrings().to(topic); // bare topic name only

if (name.length() > 255) {
  throw new IllegalArgumentException("Pub/Sub name must be at most 255 characters");
}

try { PubsubIO.readStrings().fromTopic(topic); } catch (IllegalArgumentException e) { log.error("Pub/Sub name too long: {}", e.getMessage()); }

When it happens

Trigger: validatePubsubName is invoked with a name whose length exceeds 255 while constructing a PubsubIO topic or subscription path.

Common situations: Accidentally passing the full resource path (projects/p/topics/...) instead of the bare name; programmatically generated names (timestamps + UUIDs) that balloon in size; concatenated environment/stage prefixes.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Pubsub object name is shorter than 3 characters: {name}
• Illegal project name specified in Pubsub subscription: {proj
• Pipeline update will not be possible because the following t
• Pubsub message must contain a non-empty payload or at least
• Pubsub object name cannot start with goog: {name}

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