{"record":{"id":"c4b15327c50ac076","repo":"apache/beam","slug":"unknown-key-part","errorCode":null,"errorMessage":"Unknown key part {}","messagePattern":"Unknown key part (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/MutationKeyEncoder.java","lineNumber":177,"sourceCode":"          orderedCode.writeInfinity();\n        }\n      } else {\n        if (value instanceof Boolean) {\n          writeNumber(orderedCode, part, (long) ((Boolean) value ? 0 : 1));\n        } else if (value instanceof Long) {\n          writeNumber(orderedCode, part, (long) value);\n        } else if (value instanceof Double) {\n          writeNumber(orderedCode, part, Double.doubleToLongBits((double) value));\n        } else if (value instanceof String) {\n          writeString(orderedCode, part, (String) value);\n        } else if (value instanceof ByteArray) {\n          writeBytes(orderedCode, part, (ByteArray) value);\n        } else if (value instanceof Timestamp) {\n          writeTimestamp(orderedCode, part, (Timestamp) value);\n        } else if (value instanceof Date) {\n          writeNumber(orderedCode, part, encodeDate((Date) value));\n        } else {\n          throw new IllegalArgumentException(\"Unknown key part \" + value);\n        }\n      }\n    }\n  }\n\n  private void writeBytes(OrderedCode orderedCode, KeyPart part, ByteArray bytes) {\n    if (part.isDesc()) {\n      orderedCode.writeBytesDecreasing(bytes.toByteArray());\n    } else {\n      orderedCode.writeBytes(bytes.toByteArray());\n    }\n  }\n\n  private void writeNumber(OrderedCode orderedCode, KeyPart part, long v) {\n    if (part.isDesc()) {\n      orderedCode.writeSignedNumDecreasing(v);\n    } else {\n      orderedCode.writeSignedNumIncreasing(v);","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/MutationKeyEncoder.java#L159-L195","documentation":"MutationKeyEncoder.encodeKey() has a second, value-based dispatch: for key parts whose type is not determined via Type code it checks instanceof (String, Long, ByteArray, Timestamp, Date, ...). If a key part value is none of the recognized classes it throws IllegalArgumentException('Unknown key part ...').","triggerScenarios":"Passing a key value of an unexpected Java class — e.g. a BigDecimal, Double, Boolean, or a Beam Row value that was not converted — into the key when building a Spanner mutation via encodeTableNameAndKey.","commonSituations":"Beam Row schema and the Spanner table schema disagree (e.g. schema says STRING but the value came through as a different type); custom code constructing a Mutation with wrongly typed key fields; float/double key columns not matched by the instanceof chain.","solutions":["Align the Beam schema field type with the Spanner key column type so the correct Java class (String, Long, ByteArray, Timestamp, Date) is produced.","Convert the key value explicitly (e.g. Double → correct numeric representation, java.util.Date → com.google.cloud.Date) before building the mutation.","Inspect the reported value's class in the message and add the missing conversion in your pipeline."],"exampleFix":"// before\nkey.append(myDoubleKey) // Double not recognized\n// after\nkey.append(Double.doubleToLongBits(myDoubleKey)) // store FLOAT64 key as INT64, or use supported key type","handlingStrategy":"type-guard","validationCode":"boolean ok = keyPart instanceof String || keyPart instanceof Long || keyPart instanceof ByteArray\n  || keyPart instanceof Timestamp || keyPart instanceof com.google.cloud.Date;","typeGuard":"boolean isSupportedKeyClass(Object o) { return o instanceof String || o instanceof Long || o instanceof ByteArray || o instanceof Timestamp || o instanceof com.google.cloud.Date; }","tryCatchPattern":"try { key.append(value); } catch (IllegalArgumentException e) { log.error(\"bad key part type: \" + value.getClass()); }","preventionTips":["Match Beam schema field types to the Spanner key column types exactly","Convert java.util.Date to com.google.cloud.Date and doubles to the expected representation before keying","Log value.getClass() when debugging key building"],"tags":["java","apache-beam","spanner","type-mismatch"],"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"}