apache/beam · error · IllegalStateException

Column %s has array of arrays which is prohibited in Spanner

Error message

Column %s has array of arrays which is prohibited in Spanner.

What it means

getStructArrayValue handles ARRAY columns. An ARRAY whose elements are themselves arrays (ARRAY<ARRAY<T>>) is prohibited by Cloud Spanner's data model, so this IllegalStateException is a defensive invariant check. It should only trigger if a type code arrives nested despite Spanner disallowing it.

Source

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

            .collect(toList());

        // TODO: implement logical date
      case DATE:
        return struct.getDateList(column).stream()
            .map(date -> DateTime.parse(date.toString()))
            .collect(toList());
      case INT64:
        return struct.getLongList(column);
      case FLOAT32:
        return struct.getFloatList(column);
      case FLOAT64:
        return struct.getDoubleList(column);
      case STRING:
        return struct.getStringList(column);
      case NUMERIC:
        return struct.getBigDecimalList(column);
      case ARRAY:
        throw new IllegalStateException(
            String.format("Column %s has array of arrays which is prohibited in Spanner.", column));
      case STRUCT:
        return struct.getStructList(column).stream()
            .map(
                structElem -> {
                  Schema.@Nullable FieldType fieldType = field.getType().getCollectionElementType();
                  if (fieldType == null) {
                    throw new NullPointerException(
                        "Null collection element type at field " + field.getName());
                  }

                  @Nullable Schema elementSchema = fieldType.getRowSchema();
                  if (elementSchema == null) {
                    throw new NullPointerException(
                        "Null schema element type at field " + field.getName());
                  }
                  return structToBeamRow(structElem, elementSchema);
                })

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the column definition; Spanner cannot store arrays of arrays, so fix the schema/query producing this shape.
2. If it comes from test fixtures or hand-built Type objects, correct them to a legal Spanner type.
3. Upgrade the SDK in case a fixed backend mapping resolves the misclassification.

// Spanner forbids nested arrays; validate declared schema metadata
if (arrayType.getArrayElementType().getCode() == Type.Code.ARRAY) {
  throw new IllegalStateException("ARRAY<ARRAY<T>> is prohibited in Spanner; fix schema metadata");
}

When it happens

Trigger: Reading an ARRAY-typed Spanner column where the array element type code is also ARRAY, e.g. from future/odd backend responses or mis-declared schema metadata passed into getStructArrayValue.

Common situations: Rare: schema metadata mismatch after Spanner/SDK version changes; hand-constructed Type objects in tests that model arrays of arrays.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unsupported iterable type '%s' while translating row to stru
• Unsupported spanner array type %s for column %s.
• Tuple-like arrays are unsupported. Expected a single item ty
• Array schema is not properly formatted or unsupported ({}).
• Unexpected IOException closing ByteArrayInputStream

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