{"record":{"id":"c40533c546f99f1e","repo":"apache/beam","slug":"schema-has-to-contain-s-field","errorCode":null,"errorMessage":"Schema has to contain '%s' field","messagePattern":"Schema has to contain '(.+?)' field","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/bigtable/BigtableTable.java","lineNumber":158,"sourceCode":"    Splitter.on(\",\")\n        .splitToList(commaSeparatedMapping)\n        .forEach(\n            colonSeparatedValues -> {\n              List<String> pair = Splitter.on(\":\").splitToList(colonSeparatedValues);\n              columnsMapping.putIfAbsent(pair.get(0), newHashSet());\n              columnsMapping.get(pair.get(0)).add(pair.get(1));\n            });\n    return columnsMapping;\n  }\n\n  private static String getMatcherValue(Matcher matcher, String field) {\n    String value = matcher.group(field);\n    return value == null ? \"\" : value;\n  }\n\n  private static void validateSchema(Schema schema) {\n    if (!schema.hasField(KEY)) {\n      throw new IllegalStateException(String.format(\"Schema has to contain '%s' field\", KEY));\n    } else {\n      Schema.Field keyField = schema.getField(KEY);\n      if (keyField != null && !(Schema.TypeName.STRING == keyField.getType().getTypeName())) {\n        throw new IllegalArgumentException(\n            \"key field type should be STRING but was \" + keyField.getType().getTypeName());\n      }\n    }\n  }\n\n  private static void validateMatcher(Matcher matcher, String location) {\n    if (!matcher.matches()) {\n      throw new InvalidTableException(\n          \"Bigtable location must be in the following format:\"\n              + \" 'googleapis.com/bigtable/projects/projectId/instances/instanceId/tables/tableId'\"\n              + \" but was: \"\n              + location);\n    }\n  }","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/bigtable/BigtableTable.java#L140-L176","documentation":"Every Bigtable SQL table schema must contain a 'key' field, which becomes the Bigtable row key. validateSchema throws IllegalStateException when schema.hasField(KEY) is false, i.e. the declared schema lacks the mandatory 'key' column.","triggerScenarios":"Declaring a Bigtable external table whose schema has no field named 'key' — the constructor's validateSchema fails before the table can be used for read or write.","commonSituations":"Authoring CREATE EXTERNAL TABLE DDL for bigtable provider and forgetting the 'key' column; renaming the key column to something like 'rowkey' or 'id'; auto-generated schemas from data that omitted the row-key field.","solutions":["Add a 'key' field of type STRING to the table schema: CREATE EXTERNAL TABLE ... (key STRING, ...).","Rename your intended row-key column to exactly 'key' in the schema definition.","If the key lives under a different name in source data, alias it to 'key' in the columnsMapping TBLPROPERTIES is not enough — the schema field itself must be named 'key'."],"exampleFix":"-- before\nCREATE EXTERNAL TABLE bt (id STRING, cf_val STRING) TYPE 'bigtable' LOCATION '...';\n\n-- after\nCREATE EXTERNAL TABLE bt (key STRING, cf_val STRING) TYPE 'bigtable' LOCATION '...';","handlingStrategy":"validation","validationCode":"Schema schema = table.getSchema();\nif (!schema.hasField(\"key\")) {\n  throw new IllegalArgumentException(\"Bigtable table schema must contain a 'key' field\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  BigtableTable t = new BigtableTable(table);\n} catch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Schema has to contain\")) {\n    // add the 'key' field to the schema before retrying\n  }\n}","preventionTips":["Include 'key STRING' as the first column in every bigtable table declaration.","Never rename the key column; alias source columns to 'key' upstream instead.","Lint DDL files for the presence of a 'key' field on bigtable-provider tables."],"tags":["java","beam-sql","bigtable","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}