{"record":{"id":"b07d7e27ff1f1110","repo":"apache/iceberg","slug":"unrecognized-update-requirement-cannot-convert-to","errorCode":null,"errorMessage":"Unrecognized update requirement. Cannot convert to json: %s","messagePattern":"Unrecognized update requirement\\. Cannot convert to json: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/UpdateRequirementParser.java","lineNumber":182,"sourceCode":"        return readAssertTableDoesNotExist(jsonNode);\n      case ASSERT_TABLE_UUID:\n        return readAssertTableUUID(jsonNode);\n      case ASSERT_VIEW_UUID:\n        return readAssertViewUUID(jsonNode);\n      case ASSERT_REF_SNAPSHOT_ID:\n        return readAssertRefSnapshotId(jsonNode);\n      case ASSERT_LAST_ASSIGNED_FIELD_ID:\n        return readAssertLastAssignedFieldId(jsonNode);\n      case ASSERT_LAST_ASSIGNED_PARTITION_ID:\n        return readAssertLastAssignedPartitionId(jsonNode);\n      case ASSERT_CURRENT_SCHEMA_ID:\n        return readAssertCurrentSchemaId(jsonNode);\n      case ASSERT_DEFAULT_SPEC_ID:\n        return readAssertDefaultSpecId(jsonNode);\n      case ASSERT_DEFAULT_SORT_ORDER_ID:\n        return readAssertDefaultSortOrderId(jsonNode);\n      default:\n        throw new UnsupportedOperationException(\n            String.format(\"Unrecognized update requirement. Cannot convert to json: %s\", type));\n    }\n  }\n\n  private static void writeAssertTableUUID(\n      UpdateRequirement.AssertTableUUID requirement, JsonGenerator gen) throws IOException {\n    gen.writeStringField(UUID, requirement.uuid());\n  }\n\n  private static void writeAssertViewUUID(\n      UpdateRequirement.AssertViewUUID requirement, JsonGenerator gen) throws IOException {\n    gen.writeStringField(UUID, requirement.uuid());\n  }\n\n  private static void writeAssertRefSnapshotId(\n      UpdateRequirement.AssertRefSnapshotID requirement, JsonGenerator gen) throws IOException {\n    gen.writeStringField(NAME, requirement.refName());\n    if (requirement.snapshotId() != null) {","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/UpdateRequirementParser.java#L164-L200","documentation":"Thrown by UpdateRequirementParser.fromJson when the 'type' field in the JSON is not one of the recognized requirement types. This happens when a REST catalog server (or newer client) sends an update-requirement of a type this Iceberg version does not know. The parser throws UnsupportedOperationException instead of silently dropping the assertion, because ignoring a requirement could wrongly allow an unsafe commit.","triggerScenarios":"Parsing a JSON requirements array (e.g. from a REST catalog commit response or stored file) whose 'type' value is absent from {assert-table-uuid, assert-last-assigned-field-id, assert-current-schema-id, assert-last-assigned-partition-id, assert-default-spec-id, assert-default-sort-order-id, assert-ref-snapshot-id} — typically a requirement added in a newer Iceberg spec version.","commonSituations":"Client on older Iceberg reading requirements produced by a newer REST catalog/server; typo'd or hand-edited requirement JSON; a server implementing a vendor-specific requirement extension not in the client's spec version.","solutions":["Upgrade the Iceberg client library to a version whose parser knows the requirement type sent by the server (keep client and catalog server spec versions aligned).","Check the exact 'type' string in the JSON payload for typos or unexpected values (log the payload before parsing).","If the server emits a vendor extension, either disable that server feature or filter/reject such requirements before parse — never ignore them silently.","Ensure no older shaded iceberg-core copy intercepts parsing (single consistent Iceberg version on the classpath)."],"exampleFix":"// before: iceberg-core 1.4 client parsing 1.6 server requirements\nList<UpdateRequirement> reqs = UpdateRequirementParser.fromJson(node); // throws\n// after: upgrade client\n// implementation 'org.apache.iceberg:iceberg-core:1.6.1'\n// or defensively:\nString type = node.get(\"type\").textValue();\nif (!KNOWN_TYPES.contains(type)) {\n  throw new IllegalStateException(\"Unsupported requirement type from server: \" + type);\n}","handlingStrategy":"try-catch","validationCode":"String type = jsonNode.get(\"type\") != null ? jsonNode.get(\"type\").textValue() : null;\nif (type == null || !KNOWN_REQUIREMENT_TYPES.contains(type)) {\n  throw new IllegalStateException(\"Unknown requirement type from server: \" + type);\n}","typeGuard":"boolean isKnownRequirementType(String type) {\n  return type != null && Set.of(\"assert-table-uuid\", \"assert-last-assigned-field-id\",\n      \"assert-current-schema-id\", \"assert-last-assigned-partition-id\",\n      \"assert-default-spec-id\", \"assert-default-sort-order-id\",\n      \"assert-ref-snapshot-id\").contains(type);\n}","tryCatchPattern":"try {\n  List<UpdateRequirement> reqs = UpdateRequirementParser.fromJson(node);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().startsWith(\"Unrecognized update requirement\")) {\n    throw new IllegalStateException(\"Server sent a requirement type this client does not support; upgrade iceberg-core\", e);\n  }\n  throw e;\n}","preventionTips":["Keep the Iceberg client version at or above the REST catalog server's spec version","Log raw requirement JSON before parsing to diagnose unknown 'type' values","Never ignore unknown requirements — they guard commit safety","Verify catalog server and client deploy the same Iceberg release train"],"tags":["serialization","json","version-mismatch","rest-catalog","iceberg"],"backgroundTag":"unsupported-enum-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}