{"record":{"id":"0b0aaa28f176c1b8","repo":"apache/beam","slug":"field-keyfield-should-of-type-varbinary-please-change-the","errorCode":null,"errorMessage":"Field `{keyField}` should of type `VARBINARY`. Please change the type or specify a field to write the KEY value from via TableProperties.","messagePattern":"Field `(.+?)` should of type `VARBINARY`\\. Please change the type or specify a field to write the KEY value from via TableProperties\\.","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/datastore/RowToEntity.java","lineNumber":69,"sourceCode":"  private static final Logger LOG = LoggerFactory.getLogger(RowToEntity.class);\n\n  private RowToEntity(Supplier<String> keySupplier, String kind, String keyField) {\n    this.keySupplier = keySupplier;\n    this.kind = kind;\n    this.keyField = keyField;\n  }\n\n  @Override\n  public PCollection<Entity> expand(PCollection<Row> input) {\n    boolean isFieldPresent = input.getSchema().getFieldNames().contains(keyField);\n    if (isFieldPresent) {\n      if (!input\n          .getSchema()\n          .getField(keyField)\n          .getType()\n          .getTypeName()\n          .equals(Schema.TypeName.BYTES)) {\n        throw new IllegalStateException(\n            \"Field `\"\n                + keyField\n                + \"` should of type `VARBINARY`. Please change the type or specify a field to\"\n                + \" write the KEY value from via TableProperties.\");\n      }\n      LOG.info(\"Field to use as Entity KEY is set to: `{}`.\", keyField);\n    }\n    return input.apply(ParDo.of(new RowToEntity.RowToEntityConverter(isFieldPresent)));\n  }\n\n  /**\n   * Create a PTransform instance.\n   *\n   * @param keyField Row field containing a serialized {@code Key}, must be set when using user\n   *     specified keys.\n   * @param kind DataStore `Kind` data will be written to (required when generating random {@code\n   *     Key}s).\n   * @return {@code PTransform} instance for Row to Entity conversion.","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/datastore/RowToEntity.java#L51-L87","documentation":"RowToEntity converts Beam Rows back into Datastore Entities. When a keyField is specified, the input schema's field with that name must be of Beam type BYTES, because the Entity KEY is taken from raw bytes. expand() throws this IllegalStateException when the field exists but is declared with any other type (VARBINARY in the message is a legacy label for non-BYTES).","triggerScenarios":"Applying DatastoreIO.v1().write().withKeyField(...).expand() (RowToEntity.expand) on a PCollection whose schema declares keyField as STRING/INT64/etc. rather than BYTES.","commonSituations":"Output schema from an upstream transform (e.g. BigQuery read) typed the key as STRING; changing keyField name without updating the schema; writing a row field where the user assumed the string key would be auto-encoded.","solutions":["Change the keyField column type to Schema.FieldType.BYTES in the input PCollection's schema","Or select a different BYTES-typed field as the keyField, or remove withKeyField so keys are not taken from the row","If the key is a string, encode it to bytes yourself (e.g. key.getBytes(UTF_8)) and store it in a BYTES field"],"exampleFix":"// before\nSchema schema = Schema.of(Schema.Field.of(\"key\", Schema.FieldType.STRING));\n// after\nSchema schema = Schema.of(Schema.Field.of(\"key\", Schema.FieldType.BYTES));","handlingStrategy":"validation","validationCode":"if (pc.getSchema().getFieldNames().contains(keyField)\n    && !pc.getSchema().getField(keyField).getType().getTypeName().equals(Schema.TypeName.BYTES)) {\n  throw new IllegalArgumentException(\"keyField `\" + keyField + \"` must be BYTES\");\n}","typeGuard":"boolean hasBytesKeyField(PCollection<Row> pc, String keyField) {\n  return pc.getSchema().getFieldNames().contains(keyField)\n      && pc.getSchema().getField(keyField).getType().getTypeName().equals(Schema.TypeName.BYTES);\n}","tryCatchPattern":null,"preventionTips":["Keep the KEY field BYTES end-to-end, including upstream transform output schemas","If the key is textual, encode it to bytes before it enters the PCollection","Call pc.setSchema(...) with an explicit schema rather than relying on inferred field types"],"tags":["gcp","datastore","schema","type-mismatch","beam"],"backgroundTag":"type-mismatch","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"}