apache/beam · error · IllegalArgumentException

Illegal project name specified in Pubsub subscription: {proj

Error message

Illegal project name specified in Pubsub subscription: {project}

What it means

PubsubIO.validateProjectName checks the project portion of a Pub/Sub subscription/project path against PROJECT_ID_REGEXP. If the supplied project string does not match the expected Google project-id format, an IllegalArgumentException is thrown before any API call is made.

Source

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

  private static final Pattern PUBSUB_NAME_REGEXP = Pattern.compile("[a-zA-Z][-._~%+a-zA-Z0-9]+");

  static final int PUBSUB_MESSAGE_MAX_TOTAL_SIZE = 10_000_000;

  private static final int PUBSUB_NAME_MIN_LENGTH = 3;
  private static final int PUBSUB_NAME_MAX_LENGTH = 255;

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

View on GitHub (pinned to 12126d8942)

Solutions

1. Supply a valid project id (6-30 lowercase letters, digits, hyphens; must start with a letter)
2. Interpolate/resolve environment variables before building the path
3. Strip protocol/host and extra path segments, passing only the project id
4. Validate the project id with the same regex before passing it into PubsubIO

Example fix

// before
String project = "https://console.cloud.google.com/home/dashboard?project=my-proj";
// after
String project = "my-proj"; // matches [a-z][-a-z0-9.:.]{5,29} style project-id regex

private static final Pattern PROJECT_ID = Pattern.compile("[a-z][-a-z0-9.:.]{4,28}[-a-z0-9]");
if (!PROJECT_ID.matcher(project).matches()) {
  throw new IllegalArgumentException("Invalid project id: " + project);
}

try { PubsubIO.readStrings().fromSubscription(path); } catch (IllegalArgumentException e) { log.error("Bad project name: {}", e.getMessage()); }

When it happens

Trigger: Constructing a Pub/Sub source/sink (PubsubIO.read/write, subscription or topic path parsing) where the project id fails PROJECT_ID_REGEXP.matches — e.g. empty, contains illegal characters, or is a full URL instead of a project id.

Common situations: Passing a project number, organization name, or full resource URL where a project id is expected; typos or trailing slashes in the path; env-config driven values like ${PROJECT_ID} left unsubstituted.

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 is shorter than 3 characters: {name}
• Pubsub object name is longer than 255 characters: {name}
• 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/8e5cf7d48ea7af8d. Report an issue: GitHub.