apache/iceberg · error · UnsupportedOperationException

Cannot convert metadata update action to json

Error message

Cannot convert metadata update action to json: %s

What it means

MetadataUpdateParser.fromJson switches on the 'action' field read from JSON and throws UnsupportedOperationException when the action string does not match any known MetadataUpdateType. The message text is slightly misleading — it is raised during JSON-to-update conversion, i.e. reading, not writing. It indicates the JSON contains an action this parser version does not know.

Solutions

1. Upgrade the Iceberg core library to a version that recognizes the action in the metadata JSON.
2. Inspect the 'action' field in the failing JSON and confirm it is not a typo or hand-edited value.
3. If you must consume the log with an old version, filter out updates with unrecognized actions before parsing.

Example fix

// before
MetadataUpdate update = MetadataUpdateParser.fromJson(node); // throws on unknown action
// after (upgrade Iceberg so the switch includes the new case)
case ADD_ENCRYPTION_KEY:
  return readAddEncryptionKey(node);

String action = node.get("action").asText();
Set<String> known = Set.of("assign-uuid","upgrade-format-version","add-snapshot","remove-snapshot",
    "set-snapshot-ref","remove-snapshot-ref","set-snapshot-summary","set-properties","remove-properties",
    "set-location","add-view-version","remove-view-version","set-current-view-version",
    "remove-current-view-version","add-schema","remove-schemas","add-encryption-key","remove-encryption-key");
if (!known.contains(action)) throw new IllegalStateException("Unknown update action: " + action);

try {
  MetadataUpdate update = MetadataUpdateParser.fromJson(node);
} catch (UnsupportedOperationException e) {
  LOG.warn("Unknown metadata update action, requires newer Iceberg: {}", node, e);
}

When it happens

Trigger: Calling MetadataUpdateParser.fromJson with a JSON node whose 'action' value is unknown to the installed Iceberg version, e.g. 'add-encryption-key' parsed by a version that predates encryption-key updates, or a typo/custom action in hand-edited metadata.

Common situations: Downgrading Iceberg versions and replaying metadata update logs written by newer versions; cross-version REST catalog interop where the server emits newer update actions than the client understands.

Related errors

• Cannot convert metadata update to json. Unrecognized action
• Cannot apply update to a view
• AboveMax has no value
• apply(value) is deprecated, use bind(Type).apply(value)
• apply(value) is deprecated, use bind(Type).apply(value)

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/1ec973972f08682f. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/MetadataUpdateParser.java:354

        return readSetProperties(jsonNode);
      case REMOVE_PROPERTIES:
        return readRemoveProperties(jsonNode);
      case SET_LOCATION:
        return readSetLocation(jsonNode);
      case ADD_VIEW_VERSION:
        return readAddViewVersion(jsonNode);
      case SET_CURRENT_VIEW_VERSION:
        return readCurrentViewVersionId(jsonNode);
      case REMOVE_PARTITION_SPECS:
        return readRemovePartitionSpecs(jsonNode);
      case REMOVE_SCHEMAS:
        return readRemoveSchemas(jsonNode);
      case ADD_ENCRYPTION_KEY:
        return readAddEncryptionKey(jsonNode);
      case REMOVE_ENCRYPTION_KEY:
        return readRemoveEncryptionKey(jsonNode);
      default:
        throw new UnsupportedOperationException(
            String.format("Cannot convert metadata update action to json: %s", action));
    }
  }

  private static void writeAssignUUID(MetadataUpdate.AssignUUID update, JsonGenerator gen)
      throws IOException {
    gen.writeStringField(UUID, update.uuid());
  }

  private static void writeUpgradeFormatVersion(
      MetadataUpdate.UpgradeFormatVersion update, JsonGenerator gen) throws IOException {
    gen.writeNumberField(FORMAT_VERSION, update.formatVersion());
  }

  private static void writeAddSchema(MetadataUpdate.AddSchema update, JsonGenerator gen)
      throws IOException {
    gen.writeFieldName(SCHEMA);
    SchemaParser.toJson(update.schema(), gen);

View on GitHub (pinned to 86d9c8fc54)