apache/beam · error · InvalidTableException

Bigtable location must be in the following format: 'googleap

Error message

Bigtable location must be in the following format: 'googleapis.com/bigtable/projects/projectId/instances/instanceId/tables/tableId' but was: %s

What it means

The LOCATION string of a Bigtable SQL table must match a strict pattern: it must contain googleapis.com/bigtable/projects/<projectId>/instances/<instanceId>/tables/<tableId>. validateMatcher throws InvalidTableException when the location string does not fully match this pattern, since the projectId/instanceId/tableId cannot be extracted.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/bigtable/BigtableTable.java:170

    String value = matcher.group(field);
    return value == null ? "" : value;
  }

  private static void validateSchema(Schema schema) {
    if (!schema.hasField(KEY)) {
      throw new IllegalStateException(String.format("Schema has to contain '%s' field", KEY));
    } else {
      Schema.Field keyField = schema.getField(KEY);
      if (keyField != null && !(Schema.TypeName.STRING == keyField.getType().getTypeName())) {
        throw new IllegalArgumentException(
            "key field type should be STRING but was " + keyField.getType().getTypeName());
      }
    }
  }

  private static void validateMatcher(Matcher matcher, String location) {
    if (!matcher.matches()) {
      throw new InvalidTableException(
          "Bigtable location must be in the following format:"
              + " 'googleapis.com/bigtable/projects/projectId/instances/instanceId/tables/tableId'"
              + " but was: "
              + location);
    }
  }

  private static void validateColumnsMapping(
      Map<String, Set<String>> columnsMapping, Schema schema) {
    validateColumnsMappingCount(columnsMapping, schema);
    validateColumnsMappingFields(columnsMapping, schema);
  }

  private static void validateColumnsMappingCount(
      Map<String, Set<String>> columnsMapping, Schema schema) {
    int mappingCount = columnsMapping.values().stream().mapToInt(Set::size).sum();
    // Don't count the key field
    int qualifiersCount = schema.getFieldCount() - 1;

View on GitHub (pinned to 12126d8942)

Solutions

Use the exact format: LOCATION 'bigtable://googleapis.com/bigtable/projects/<projectId>/instances/<instanceId>/tables/<tableId>'.
Verify each path segment exists and is spelled 'projects/', 'instances/', 'tables/' with all three identifiers filled in.
Confirm project, instance and table IDs against `gcloud bigtable instances tables list --instance=<instanceId>`.

Example fix

-- before
LOCATION 'bigtable://my-instance/my-table'

-- after
LOCATION 'bigtable://googleapis.com/bigtable/projects/my-project/instances/my-instance/tables/my-table'

Defensive patterns

Strategy: validation

Validate before calling

Pattern p = Pattern.compile("googleapis\.com/bigtable/projects/(?<projectId>[^/]+)/instances/(?<instanceId>[^/]+)/tables/(?<tableId>[^/]+)$");
if (location == null || !p.matcher(location).matches()) {
  throw new IllegalArgumentException("LOCATION must match bigtable://googleapis.com/bigtable/projects/{p}/instances/{i}/tables/{t}");
}

Try / catch

try {
  BigtableTable t = new BigtableTable(table);
} catch (InvalidTableException e) {
  if (e.getMessage().contains("location must be in the following format")) {
    // correct the LOCATION string to the documented resource URL format
  }
}

Prevention

Copy the LOCATION format from working examples, not from the Bigtable console URL.
Keep all three identifiers (project, instance, table) in the path — none may be omitted.
Verify IDs with gcloud bigtable commands before embedding them in DDL.

When it happens

Trigger: Supplying a LOCATION with wrong scheme (e.g. 'bigtable://mytable' or an https URL to the console), missing path segments (no /tables/<id>), or typos like 'project/' instead of 'projects/'.

Common situations: Pasting a Bigtable console URL instead of the resource path; omitting 'tables/tableId'; misspelling segments (instance vs instances); using a relative table name instead of the full resource URL.

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/dd7230c734f1954b. Report an issue: GitHub.