{"record":{"id":"664a77c46946a0d4","repo":"apache/beam","slug":"invalid-field-id-id-for-schema-schema","errorCode":null,"errorMessage":"Invalid field id <id> for schema <schema>","messagePattern":"Invalid field id <id> for schema <schema>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/FieldAccessDescriptor.java","lineNumber":625,"sourceCode":"    if (TypeName.ROW.equals(type.getTypeName())) {\n      return type.getRowSchema();\n    } else if (type.getTypeName().isCollectionType()) {\n      return getFieldSchema(type.getCollectionElementType());\n    } else if (TypeName.MAP.equals(type.getTypeName())) {\n      return getFieldSchema(type.getMapValueType());\n    } else if (TypeName.LOGICAL_TYPE.equals(type.getTypeName())) {\n      return getFieldSchema(type.getLogicalType().getBaseType());\n    } else {\n      throw new IllegalArgumentException(\n          \"FieldType \" + type + \" must be either a row or a container containing rows\");\n    }\n  }\n\n  private static void validateFieldDescriptor(Schema schema, FieldDescriptor fieldDescriptor) {\n    Integer fieldId = fieldDescriptor.getFieldId();\n    if (fieldId != null) {\n      if (fieldId < 0 || fieldId >= schema.getFieldCount()) {\n        throw new IllegalArgumentException(\"Invalid field id \" + fieldId + \" for schema \" + schema);\n      }\n    }\n    // If qualifiers were specified, validate them.\n    // For example, if a selector was a[*][*], then a needs to be a List of a List.\n    Field field =\n        (fieldId != null)\n            ? schema.getField(fieldId)\n            : schema.getField(fieldDescriptor.getFieldName());\n    FieldType fieldType = field.getType();\n    for (Qualifier qualifier : fieldDescriptor.getQualifiers()) {\n      switch (qualifier.getKind()) {\n        case LIST:\n          checkArgument(qualifier.getList().equals(ListQualifier.ALL));\n          checkArgument(fieldType.getTypeName().isCollectionType());\n          fieldType = fieldType.getCollectionElementType();\n          break;\n        case MAP:\n          checkArgument(qualifier.getMap().equals(MapQualifier.ALL));","sourceCodeStart":607,"sourceCodeEnd":643,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/FieldAccessDescriptor.java#L607-L643","documentation":"FieldAccessDescriptor.validateFieldDescriptor checks that any field selected by numeric id is within bounds of the target schema (0 <= id < schema.getFieldCount()). This IllegalArgumentException means a FieldDescriptor referenced a field id that doesn't exist in the schema being resolved against.","triggerScenarios":"Resolving a FieldAccessDescriptor built with withFieldId/FieldDescriptor.byId against a schema with fewer fields — e.g. id 5 on a 3-field schema; typically after schema version drift or resolving one schema's descriptor against a different schema.","commonSituations":"Caching FieldAccessDescriptor instances across schema versions; programmatic field-id lookups computed off a stale Schema; DoFns selecting fields from an upstream schema that changed shape.","solutions":["Validate fieldId against schema.getFieldCount() before resolving; clamp or remap stale ids.","Prefer withFieldNames (by name) over byId so lookups survive schema evolution.","Regenerate descriptors whenever the source Schema changes.","Log the schema (included in the message) and align the descriptor to it."],"exampleFix":"// before\nFieldAccessDescriptor.withFieldIds(5).resolve(3FieldSchema)\n\n// after\nFieldAccessDescriptor.withFieldNames(\"expectedField\").resolve(schema);","handlingStrategy":"validation","validationCode":"if (fieldId < 0 || fieldId >= schema.getFieldCount()) throw new IllegalArgumentException(\"fieldId out of range: \" + fieldId);","typeGuard":"static boolean validFieldId(Schema schema, int id) { return id >= 0 && id < schema.getFieldCount(); }","tryCatchPattern":"try { accessDescriptor.resolve(schema); }\ncatch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Invalid field id\")) { /* re-derive descriptor from current schema */ } throw e;\n}","preventionTips":["Prefer withFieldNames over withFieldIds to survive schema evolution","Rebuild descriptors whenever the schema changes version","Cache schemas and descriptors together, never separately"],"tags":["beam-schemas","field-selection","index-out-of-range"],"backgroundTag":"index-out-of-range","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"}