apache/beam · error · IllegalStateException

LOCATION is required

Error message

LOCATION is required

What it means

BigtableTable wraps a Bigtable-backed SQL table in Beam SQL and requires the table's LOCATION property to parse out projectId, instanceId and tableId. When table.getLocation() returns null there is no location string to validate or parse, so the constructor fails fast with IllegalStateException. The location cannot be defaulted or inferred, so construction is aborted.

Source

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

      Pattern.compile(
          "(?<host>.+)/bigtable/projects/(?<projectId>.+)/instances/(?<instanceId>.+)/tables/(?<tableId>.+)");

  private final String projectId;
  private final String instanceId;
  private final String tableId;
  private String emulatorHost = "";

  private boolean useFlatSchema = false;

  private Map<String, Set<String>> columnsMapping = newHashMap();

  BigtableTable(Table table) {
    super(table.getSchema());
    validateSchema(schema);

    String location = table.getLocation();
    if (location == null) {
      throw new IllegalStateException("LOCATION is required");
    }
    Matcher matcher = locationPattern.matcher(location);
    validateMatcher(matcher, location);

    this.projectId = getMatcherValue(matcher, "projectId");
    this.instanceId = getMatcherValue(matcher, "instanceId");
    this.tableId = getMatcherValue(matcher, "tableId");
    String host = getMatcherValue(matcher, "host"); // googleapis.com or localhost:<PORT>
    if (!"googleapis.com".equals(host)) {
      this.emulatorHost = host;
    }

    ObjectNode properties = table.getProperties();
    if (properties.has(COLUMNS_MAPPING)) {
      columnsMapping = parseColumnsMapping(properties.get(COLUMNS_MAPPING).asText());
      validateColumnsMapping(columnsMapping, schema);
      useFlatSchema = true;
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Add a LOCATION clause/property in the form 'bigtable://googleapis.com/bigtable/projects/<projectId>/instances/<instanceId>/tables/<tableId>' to the table definition.
2. If building the Table object in code, call Table.withLocation(...) with a valid bigtable URL before passing it to the provider.
3. Check catalog/metadata files for the table and add the missing location field, then reload the table provider.

Example fix

-- before
CREATE EXTERNAL TABLE bt_table (key STRING, cf_col STRING)
TYPE 'bigtable'
TBLPROPERTIES '{...}';

-- after
CREATE EXTERNAL TABLE bt_table (key STRING, cf_col STRING)
TYPE 'bigtable'
LOCATION 'bigtable://googleapis.com/bigtable/projects/my-project/instances/my-instance/tables/my-table'
TBLPROPERTIES '{...}';

String location = table.getLocation();
if (location == null || location.isEmpty()) {
  throw new IllegalArgumentException("Bigtable table requires a LOCATION (bigtable://googleapis.com/bigtable/projects/...) before use");
}

try {
  BigtableTable t = new BigtableTable(table);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("LOCATION is required")) {
    // surface a config-fix message pointing at the LOCATION clause
  }
}

When it happens

Trigger: Creating or loading a Bigtable SQL table (CREATE EXTERNAL TABLE ... LOCATION or provider catalog metadata) where the LOCATION clause/property is omitted entirely, so table.getLocation() is null when the BigtableTable constructor runs.

Common situations: Writing CREATE EXTERNAL TABLE DDL against provider 'bigtable' without a LOCATION; programmatic TableProvider catalog entries built with a Table that has no location set; migration from configs where LOCATION used to be optional.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Schema fields count: '%s' does not fit columnsMapping count:
• columnsMapping '%s' does not fit to schema field names '%s'
• Write to Cloud Bigtable is supported for flat schema only.
• Schema has to contain '%s' field
• key field type should be STRING but was %s

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