apache/beam · error · IllegalArgumentException

Unsupported format for BigQuery table path: '{linkedResource

Error message

Unsupported format for BigQuery table path: '{linkedResource}'

What it means

BigQueryTableFactory resolves a DataCatalog Entry's linked resource into project/dataset/table coordinates. The linked resource URI path must match the expected BigQuery path pattern (projects/{p}/datasets/{d}/tables/{t}); otherwise an IllegalArgumentException is thrown because the table location cannot be parsed.

Source

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

    if (!URI.create(entry.getLinkedResource()).getAuthority().equalsIgnoreCase(BIGQUERY_API)) {
      return Optional.empty();
    }

    return Optional.of(
        Table.builder()
            .location(getLocation(entry))
            .properties(TableUtils.emptyProperties().put("truncateTimestamps", truncateTimestamps))
            .type("bigquery")
            .comment(""));
  }

  private static String getLocation(Entry entry) {
    URI entryName = URI.create(entry.getLinkedResource());
    String bqPath = entryName.getPath();

    Matcher bqPathMatcher = BQ_PATH_PATTERN.matcher(bqPath);
    if (!bqPathMatcher.matches()) {
      throw new IllegalArgumentException(
          "Unsupported format for BigQuery table path: '" + entry.getLinkedResource() + "'");
    }

    String project = bqPathMatcher.group("PROJECT");
    String dataset = bqPathMatcher.group("DATASET");
    String table = bqPathMatcher.group("TABLE");

    return String.format("%s:%s.%s", project, dataset, table);
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

  1. Verify the entry's linkedResource matches projects/<project>/datasets/<dataset>/tables/<table> and point the entry at a real BigQuery table.
  2. If the entry is a view or dataset, materialize/point to an actual table resource in Data Catalog.
  3. Strip any partition decorators (@date) or extra path segments from the resource name before lookup.

Example fix

// before (entry linkedResource)
// projects/my-proj/datasets/my_ds  (dataset, not a table)

// after
// projects/my-proj/datasets/my_ds/tables/my_table
Defensive patterns

Strategy: validation

Validate before calling

String linked = entry.getLinkedResource();
URI uri = URI.create(linked);
boolean ok = Pattern.matches("^/projects/[^/]+/datasets/[^/]+/tables/[^/]+$", uri.getPath());
if (!ok) throw new IllegalArgumentException("Not a BigQuery table path: " + linked);

Try / catch

try {
  Table t = provider.getTable(name);
} catch (IllegalArgumentException e) {
  // path did not match BigQuery table pattern; inspect linkedResource
}

Prevention

When it happens

Trigger: Registering or looking up a DataCatalog entry whose linkedResource is not a BigQuery table path — e.g. a BigQuery dataset, a non-BigQuery resource type (GCS, Pub/Sub), a partitioned table suffix like @YYYYMMDD, or a truncated/malformed resource name.

Common situations: Cataloging views or datasets instead of tables, entries pointing at other GCP services, using legacy-style or aliased resource names, or region-tagged paths like projects/p/locations/eu/... that the pattern does not accept.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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