{"record":{"id":"8cf47be7f25dfb5e","repo":"apache/beam","slug":"unable-to-parse-gcs-entry-entryname","errorCode":null,"errorMessage":"Unable to parse GCS entry '{entryName}'","messagePattern":"Unable to parse GCS entry '(.+?)'","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/GcsTableFactory.java","lineNumber":42,"sourceCode":"import org.apache.beam.sdk.extensions.sql.TableUtils;\nimport org.apache.beam.sdk.extensions.sql.meta.Table;\n\n/** {@link TableFactory} that understands Data Catalog GCS entries. */\nclass GcsTableFactory implements TableFactory {\n\n  /** Creates a Beam SQL table description from a GCS fileset entry. */\n  @Override\n  public Optional<Table.Builder> tableBuilder(Entry entry) {\n    if (!entry.hasGcsFilesetSpec()) {\n      return Optional.empty();\n    }\n\n    GcsFilesetSpec gcsFilesetSpec = entry.getGcsFilesetSpec();\n    List<String> filePatterns = gcsFilesetSpec.getFilePatternsList();\n\n    // We support exactly one 'file_patterns' field and nothing else at the moment\n    if (filePatterns.size() != 1) {\n      throw new UnsupportedOperationException(\n          \"Unable to parse GCS entry '\" + entry.getName() + \"'\");\n    }\n\n    String filePattern = filePatterns.get(0);\n\n    if (!filePattern.startsWith(\"gs://\")) {\n      throw new UnsupportedOperationException(\n          \"Unsupported file pattern. \"\n              + \"Only file patterns with 'gs://' schema are supported at the moment.\");\n    }\n\n    return Optional.of(\n        Table.builder()\n            .type(\"text\")\n            .location(filePattern)\n            .properties(TableUtils.emptyProperties())\n            .comment(\"\"));\n  }","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/GcsTableFactory.java#L24-L60","documentation":"GcsTableFactory.tableBuilder throws this when a Data Catalog entry's GCS fileset spec does not contain exactly one file pattern. The factory supports exactly one 'file_patterns' entry and nothing else; zero or multiple patterns make the entry unparseable.","triggerScenarios":"Entry.getGcsFilesetSpec().getFilePatternsList() has size != 1 (empty list or more than one pattern) when building a table from a Data Catalog GCS entry.","commonSituations":"Data Catalog entries created via API/UI with multiple file patterns, or entries whose file_patterns field was never populated.","solutions":["Edit the Data Catalog entry so its GCS fileset spec has exactly one file pattern","Split multiple patterns into separate entries (one pattern per table)","Confirm the entry is a GCS fileset entry, not another type routed to the wrong factory","Fall back to defining the table inline in Beam SQL instead of via Data Catalog"],"exampleFix":"// before\nfile_patterns: ['gs://b/a/*.json', 'gs://b/b/*.json']\n// after\nfile_patterns: ['gs://b/**/*.json']","handlingStrategy":"validation","validationCode":"if (entry.hasGcsFilesetSpec()) {\n  int n = entry.getGcsFilesetSpec().getFilePatternsCount();\n  if (n != 1) throw new IllegalArgumentException(\"Expected exactly 1 file pattern, got \" + n);\n}","typeGuard":"static boolean hasSingleFilePattern(Entry e) {\n  return e.hasGcsFilesetSpec() && e.getGcsFilesetSpec().getFilePatternsCount() == 1;\n}","tryCatchPattern":"try {\n  Optional<Table.Builder> b = gcsFactory.tableBuilder(entry);\n} catch (UnsupportedOperationException ex) {\n  LOG.error(\"GCS entry must have exactly one file pattern: {}\", entry.getName(), ex);\n}","preventionTips":["Author entries with exactly one file pattern; use globs like gs://b/**/*.json for multiple files","Validate file_patterns count when creating entries via API automation","Document the one-pattern constraint for teams creating catalog entries"],"tags":["datacatalog","gcs","fileset"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}