{"record":{"id":"054d2866311b3687","repo":"apache/beam","slug":"illegal-pubsub-object-name-specified-name-please-see-javadoc","errorCode":null,"errorMessage":"Illegal Pubsub object name specified: {name} Please see Javadoc for naming rules.","messagePattern":"Illegal Pubsub object name specified: (.+?) Please see Javadoc for naming rules\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubIO.java","lineNumber":254,"sourceCode":"  }\n\n  private static void validatePubsubName(String name) {\n    if (name.length() < PUBSUB_NAME_MIN_LENGTH) {\n      throw new IllegalArgumentException(\n          \"Pubsub object name is shorter than 3 characters: \" + name);\n    }\n    if (name.length() > PUBSUB_NAME_MAX_LENGTH) {\n      throw new IllegalArgumentException(\n          \"Pubsub object name is longer than 255 characters: \" + name);\n    }\n\n    if (name.startsWith(\"goog\")) {\n      throw new IllegalArgumentException(\"Pubsub object name cannot start with goog: \" + name);\n    }\n\n    Matcher match = PUBSUB_NAME_REGEXP.matcher(name);\n    if (!match.matches()) {\n      throw new IllegalArgumentException(\n          \"Illegal Pubsub object name specified: \"\n              + name\n              + \" Please see Javadoc for naming rules.\");\n    }\n  }\n\n  /** Populate common {@link DisplayData} between Pubsub source and sink. */\n  private static void populateCommonDisplayData(\n      DisplayData.Builder builder,\n      @Nullable String timestampAttribute,\n      @Nullable String idAttribute,\n      @Nullable ValueProvider<PubsubTopic> topic) {\n    builder\n        .addIfNotNull(\n            DisplayData.item(\"timestampAttribute\", timestampAttribute)\n                .withLabel(\"Timestamp Attribute\"))\n        .addIfNotNull(DisplayData.item(\"idAttribute\", idAttribute).withLabel(\"ID Attribute\"))\n        .addIfNotNull(DisplayData.item(\"topic\", topic).withLabel(\"Pubsub Topic\"));","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubIO.java#L236-L272","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the name to match [a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}: start with a letter, use only letters/digits/-/_/./~/%/+.","Extract and validate only the name component if you mistakenly passed the full projects/.../topics/... path where a bare name is expected.","Pre-validate names with the same regex before calling the PubsubIO builder."],"exampleFix":"// before\nString topic = \"my topic!\"; // invalid chars\nPubsubIO.writeStrings().to(\"projects/p/topics/\" + topic);\n// after\nString topic = \"my-topic\";\nif (!topic.matches(\"[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}\")) throw new IllegalArgumentException(topic);\nPubsubIO.writeStrings().to(\"projects/p/topics/\" + topic);","handlingStrategy":"validation","validationCode":"private static final Pattern NAME = Pattern.compile(\"[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}\");\nstatic void checkName(String name) {\n  if (name == null || !NAME.matcher(name).matches())\n    throw new IllegalArgumentException(\"Invalid Pub/Sub name: \" + name);\n}","typeGuard":"boolean isLegalPubsubName(String name) {\n  return name != null && Pattern.compile(\"[a-zA-Z][a-zA-Z0-9-_.~%+]{2,254}\").matcher(name).matches();\n}","tryCatchPattern":"try {\n  return PubsubIO.readStrings().fromSubscription(path);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Illegal Pubsub object name\"))\n    throw new ConfigException(\"Name violates Pub/Sub naming rules: \" + path, e);\n  throw e;\n}","preventionTips":["Validate names against the Pub/Sub regex at config load time","Sanitize user/env-derived strings before interpolating into names","Add unit tests covering your naming template"],"tags":["java","pubsub","naming","beam"],"backgroundTag":"invalid-identifier-format","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T02:17:10.978Z"}