apache/beam · error · IllegalArgumentException

Table reference is not in…

Error message

Table reference is not in projects/[project_id]/datasets/[dataset_id]/tables/[table_id] format: " + tableUrn

What it means

parseTableUrn() validates that a table resource string matches the canonical BigQuery URN format projects/[project_id]/datasets/[dataset_id]/tables/[table_id]. If the regex TABLE_URN_SPEC doesn't match, the string cannot be decomposed into project/dataset/table, so it throws IllegalArgumentException.

Solutions

1. Convert the string to the full URN form: projects/<project>/datasets/<dataset>/tables/<table>.
2. If you have a tableSpec instead, use BigQueryHelpers.parseString/TableReference parsing (parseTableSpec) rather than parseTableUrn.
3. Log the input string and validate its shape before calling.

Example fix

// before
TableReference ref = BigQueryHelpers.parseTableUrn("my-project:my_dataset.my_table");

// after
TableReference ref = BigQueryHelpers.parseTableUrn(
    "projects/my-project/datasets/my_dataset/tables/my_table");

static boolean isValidTableUrn(String urn) {
  return urn != null && urn.matches("projects/[^/]+/datasets/[^/]+/tables/[^/]+");
}

try {
  TableReference ref = BigQueryHelpers.parseTableUrn(urn);
} catch (IllegalArgumentException e) {
  // fall back to parseTableSpec or fix the URN format
}

When it happens

Trigger: Calling BigQueryHelpers.parseTableUrn() with a string that isn't a full table URN, e.g. 'my_dataset.my_table', 'project:dataset.table', a tableSpec, or a URL.

Common situations: Passing a tableSpec ('project:dataset.table') or legacy notation where a URN is required (e.g. SchemaTransform identifiers, ResourceIds), or copy-pasting a dataset-only reference.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• input is expected to be empty
• 2xx codes should not be exceptions. Got status code
• A function must be provided to convert the input type into…
• ApproximateUnique.PerKey needs an estimation error between…
• AUTO is not supported for writing

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

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryHelpers.java:569

    return ref.setDatasetId(dataset).setTableId(table);
  }

  private static IllegalArgumentException invalidTableSpec(String tableSpec) {
    return new IllegalArgumentException(
        String.format(
            "Table specification [%s] is not in one of the expected formats ("
                + " [project_id]:[dataset_id].[table_id],"
                + " [project_id].[dataset_id].[table_id],"
                + " [dataset_id].[table_id],"
                + " [project_id]:[catalog_id].[namespace_id].[table_id],"
                + " [project_id].[catalog_id].[namespace_id].[table_id])",
            tableSpec));
  }

  public static TableReference parseTableUrn(String tableUrn) {
    Matcher match = BigQueryIO.TABLE_URN_SPEC.matcher(tableUrn);
    if (!match.matches()) {
      throw new IllegalArgumentException(
          "Table reference is not in projects/[project_id]/datasets/[dataset_id]/tables/[table_id] "
              + "format: "
              + tableUrn);
    }

    return new TableReference()
        .setProjectId(checkStateNotNull(match.group("PROJECT")))
        .setDatasetId(checkStateNotNull(match.group("DATASET")))
        .setTableId(checkStateNotNull(match.group("TABLE")));
  }

  /** Strip off any partition decorator information from a tablespec. */
  public static String stripPartitionDecorator(String tableSpec) {
    int index = tableSpec.lastIndexOf('$');
    return (index == -1) ? tableSpec : tableSpec.substring(0, index);
  }

  static String jobToPrettyString(@Nullable Job job) throws IOException {

View on GitHub (pinned to 12126d8942)