apache/beam · error · IllegalArgumentException

Unknown key part {}

Error message

Unknown key part {}

What it means

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 ...').

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/MutationKeyEncoder.java:177

          orderedCode.writeInfinity();
        }
      } else {
        if (value instanceof Boolean) {
          writeNumber(orderedCode, part, (long) ((Boolean) value ? 0 : 1));
        } else if (value instanceof Long) {
          writeNumber(orderedCode, part, (long) value);
        } else if (value instanceof Double) {
          writeNumber(orderedCode, part, Double.doubleToLongBits((double) value));
        } else if (value instanceof String) {
          writeString(orderedCode, part, (String) value);
        } else if (value instanceof ByteArray) {
          writeBytes(orderedCode, part, (ByteArray) value);
        } else if (value instanceof Timestamp) {
          writeTimestamp(orderedCode, part, (Timestamp) value);
        } else if (value instanceof Date) {
          writeNumber(orderedCode, part, encodeDate((Date) value));
        } else {
          throw new IllegalArgumentException("Unknown key part " + value);
        }
      }
    }
  }

  private void writeBytes(OrderedCode orderedCode, KeyPart part, ByteArray bytes) {
    if (part.isDesc()) {
      orderedCode.writeBytesDecreasing(bytes.toByteArray());
    } else {
      orderedCode.writeBytes(bytes.toByteArray());
    }
  }

  private void writeNumber(OrderedCode orderedCode, KeyPart part, long v) {
    if (part.isDesc()) {
      orderedCode.writeSignedNumDecreasing(v);
    } else {
      orderedCode.writeSignedNumIncreasing(v);

View on GitHub (pinned to 12126d8942)

Solutions

1. Align the Beam schema field type with the Spanner key column type so the correct Java class (String, Long, ByteArray, Timestamp, Date) is produced.
2. Convert the key value explicitly (e.g. Double → correct numeric representation, java.util.Date → com.google.cloud.Date) before building the mutation.
3. Inspect the reported value's class in the message and add the missing conversion in your pipeline.

Example fix

// before
key.append(myDoubleKey) // Double not recognized
// after
key.append(Double.doubleToLongBits(myDoubleKey)) // store FLOAT64 key as INT64, or use supported key type

boolean ok = keyPart instanceof String || keyPart instanceof Long || keyPart instanceof ByteArray
  || keyPart instanceof Timestamp || keyPart instanceof com.google.cloud.Date;

boolean isSupportedKeyClass(Object o) { return o instanceof String || o instanceof Long || o instanceof ByteArray || o instanceof Timestamp || o instanceof com.google.cloud.Date; }

try { key.append(value); } catch (IllegalArgumentException e) { log.error("bad key part type: " + value.getClass()); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unknown type {}
• Provided coders for type arguments of %s contain incompatibi
• Can't cast non-numeric types: +input
• Can't cast numbers to non-numeric type: +output
• KeepFn %s must return a boolean, but returns %s instead.

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