apache/beam · error · IllegalArgumentException

Pubsub object name is shorter than 3 characters: {name}

Error message

Pubsub object name is shorter than 3 characters: {name}

What it means

Pub/Sub topic and subscription names must be at least 3 characters (PUBSUB_NAME_MIN_LENGTH). validatePubsubName throws IllegalArgumentException when the configured name is shorter, preventing a doomed API call to create or reference the resource.

Source

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

  private static final String SUBSCRIPTION_RANDOM_TEST_PREFIX = "_random/";
  private static final String SUBSCRIPTION_STARTING_SIGNAL = "_starting_signal/";
  private static final String TOPIC_DEV_NULL_TEST_NAME = "/topics/dev/null";

  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.");
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a topic/subscription name of at least 3 characters (letters, digits, hyphens, underscores, periods)
2. Fix config resolution so placeholders expand to the real resource name
3. Log/inspect the parsed name before building the pipeline to catch truncation
4. Validate name length in application config validation before launching the job

Example fix

// before
String topic = conf.getOrDefault("topic", "ab");
// after
String topic = conf.getOrDefault("topic", "my-events-topic"); // >= 3 chars

if (name == null || name.length() < 3) {
  throw new IllegalArgumentException("Pub/Sub name must be at least 3 characters: " + name);
}

try { PubsubIO.readStrings().fromSubscription(sub); } catch (IllegalArgumentException e) { log.error("Invalid Pub/Sub name: {}", e.getMessage()); }

When it happens

Trigger: Creating/validating a PubsubIO topic or subscription whose name string has fewer than 3 characters, e.g. topic "ab" or an empty name after path parsing.

Common situations: Unsubstituted template variables resulting in very short strings; truncated config values; accidentally passing a prefix or delimiter instead of the full name.

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 longer than 255 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/8dfad427831bbefd. Report an issue: GitHub.