{"record":{"id":"fc73f793a385520f","repo":"apache/beam","slug":"unexpected-null-schema","errorCode":null,"errorMessage":"Unexpected null schema!","messagePattern":"Unexpected null schema!","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BeamRowToStorageApiProto.java","lineNumber":214,"sourceCode":"    TableSchema.Builder builder = TableSchema.newBuilder();\n    for (Field field : schema.getFields()) {\n      builder.addFields(fieldDescriptorFromBeamField(field));\n    }\n    return builder.build();\n  }\n\n  private static TableFieldSchema fieldDescriptorFromBeamField(Field field) {\n    TableFieldSchema.Builder builder = TableFieldSchema.newBuilder();\n    if (StorageApiCDC.COLUMNS.contains(field.getName())) {\n      throw new RuntimeException(\"Reserved field name \" + field.getName() + \" in user schema.\");\n    }\n    builder = builder.setName(field.getName().toLowerCase());\n\n    switch (field.getType().getTypeName()) {\n      case ROW:\n        @Nullable Schema rowSchema = field.getType().getRowSchema();\n        if (rowSchema == null) {\n          throw new RuntimeException(\"Unexpected null schema!\");\n        }\n        builder = builder.setType(TableFieldSchema.Type.STRUCT);\n        for (Schema.Field nestedField : rowSchema.getFields()) {\n          builder = builder.addFields(fieldDescriptorFromBeamField(nestedField));\n        }\n        break;\n      case ARRAY:\n      case ITERABLE:\n        @Nullable FieldType elementType = field.getType().getCollectionElementType();\n        if (elementType == null) {\n          throw new RuntimeException(\"Unexpected null element type on \" + field.getName());\n        }\n        TypeName containedTypeName =\n            Preconditions.checkNotNull(\n                elementType.getTypeName(),\n                \"Null type name found in contained type at %s\",\n                field.getName());\n        Preconditions.checkState(","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BeamRowToStorageApiProto.java#L196-L232","documentation":"fieldDescriptorFromBeamField, when handling a ROW-typed Beam field, calls field.getType().getRowSchema() and throws \"Unexpected null schema!\" if it returns null. A ROW FieldType must always carry a nested Schema; a null result means the field type was constructed without one, so nested TableFieldSchema fields can't be derived.","triggerScenarios":"Building a Beam Schema field with Schema.FieldType.row(null) or a FieldType incorrectly typed as ROW without attaching the nested schema, then writing via BigQueryIO Storage API","commonSituations":"Reflection/inference-based schema builders producing ROW fields without schemas; custom FieldType factories; deserialized schemas missing nested definitions.","solutions":["Attach the nested schema: Schema.FieldType.row(nestedSchema) instead of a bare ROW type","Verify every ROW field in your Schema has a non-null row schema before writing","Check the code path that constructs your Schema (e.g. from a POJO) to ensure nested objects are registered","Rebuild nested fields with Schema.builder().add... to guarantee a complete schema"],"exampleFix":"// before\nSchema.FieldType rowType = Schema.FieldType.row(null); // or bare ROW\n// after\nSchema.FieldType rowType = Schema.FieldType.row(nestedSchema);","handlingStrategy":"validation","validationCode":"// Java\nfor (Schema.Field f : beamSchema.getFields()) {\n  if (f.getType().getTypeName() == TypeName.ROW && f.getType().getRowSchema() == null) {\n    throw new IllegalStateException(\"ROW field without nested schema: \" + f.getName());\n  }\n}","typeGuard":"// Java\nSchema nested = fieldType.getRowSchema();\nif (nested != null) { /* safe to recurse */ }","tryCatchPattern":"// Java\ntry {\n  descriptor = BeamRowToStorageApiProto.protoTableSchemaFromBeamSchema(beamSchema);\n} catch (RuntimeException e) {\n  if (e.getMessage().equals(\"Unexpected null schema!\")) {\n    // rebuild the schema attaching nested row schemas\n  }\n  throw e;\n}","preventionTips":["Always construct ROW fields via Schema.FieldType.row(nestedSchema)","Validate nested schemas recursively before pipeline submission","Avoid hand-building FieldTypes with raw TypeName values"],"tags":["java","bigquery","beam-schema","null-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-20T03:17:13.778Z"}