apache/beam · error · UnsupportedOperationException

Unable to parse GCS entry

Error message

Unable to parse GCS entry '{entryName}'

What it means

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.

Solutions

1. Edit the Data Catalog entry so its GCS fileset spec has exactly one file pattern
2. Split multiple patterns into separate entries (one pattern per table)
3. Confirm the entry is a GCS fileset entry, not another type routed to the wrong factory
4. Fall back to defining the table inline in Beam SQL instead of via Data Catalog

Example fix

// before
file_patterns: ['gs://b/a/*.json', 'gs://b/b/*.json']
// after
file_patterns: ['gs://b/**/*.json']

if (entry.hasGcsFilesetSpec()) {
  int n = entry.getGcsFilesetSpec().getFilePatternsCount();
  if (n != 1) throw new IllegalArgumentException("Expected exactly 1 file pattern, got " + n);
}

static boolean hasSingleFilePattern(Entry e) {
  return e.hasGcsFilesetSpec() && e.getGcsFilesetSpec().getFilePatternsCount() == 1;
}

try {
  Optional<Table.Builder> b = gcsFactory.tableBuilder(entry);
} catch (UnsupportedOperationException ex) {
  LOG.error("GCS entry must have exactly one file pattern: {}", entry.getName(), ex);
}

When it happens

Trigger: Entry.getGcsFilesetSpec().getFilePatternsList() has size != 1 (empty list or more than one pattern) when building a table from a Data Catalog GCS entry.

Common situations: Data Catalog entries created via API/UI with multiple file patterns, or entries whose file_patterns field was never populated.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unsupported file pattern. Only file patterns with 'gs://'…
• Array of arrays not supported in DataCatalog schemas
• artifact not staged
• Basepath %r must be GCS path.
• BigQuery temp location expected a valid 'gs://' path, but…

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

Appendix: source

Thrown at sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/GcsTableFactory.java:42

import org.apache.beam.sdk.extensions.sql.TableUtils;
import org.apache.beam.sdk.extensions.sql.meta.Table;

/** {@link TableFactory} that understands Data Catalog GCS entries. */
class GcsTableFactory implements TableFactory {

  /** Creates a Beam SQL table description from a GCS fileset entry. */
  @Override
  public Optional<Table.Builder> tableBuilder(Entry entry) {
    if (!entry.hasGcsFilesetSpec()) {
      return Optional.empty();
    }

    GcsFilesetSpec gcsFilesetSpec = entry.getGcsFilesetSpec();
    List<String> filePatterns = gcsFilesetSpec.getFilePatternsList();

    // We support exactly one 'file_patterns' field and nothing else at the moment
    if (filePatterns.size() != 1) {
      throw new UnsupportedOperationException(
          "Unable to parse GCS entry '" + entry.getName() + "'");
    }

    String filePattern = filePatterns.get(0);

    if (!filePattern.startsWith("gs://")) {
      throw new UnsupportedOperationException(
          "Unsupported file pattern. "
              + "Only file patterns with 'gs://' schema are supported at the moment.");
    }

    return Optional.of(
        Table.builder()
            .type("text")
            .location(filePattern)
            .properties(TableUtils.emptyProperties())
            .comment(""));
  }

View on GitHub (pinned to 12126d8942)