apache/iceberg · error · IllegalArgumentException

Cannot convert metadata update to json. Unrecognized action

Error message

Cannot convert metadata update to json. Unrecognized action: %s

What it means

MetadataUpdateParser.toJson switches on the update's action enum and throws IllegalArgumentException when the action has no writer case. This happens when a new MetadataUpdate type is added without extending the parser, or when serializing an update from a newer Iceberg version whose action the current parser does not recognize.

Solutions

1. Upgrade the Iceberg core library so MetadataUpdateParser covers the action being serialized.
2. Verify no custom MetadataUpdate implementations are being passed to the parser; implement custom serialization if needed.
3. Check the action value in the failing update and confirm it exists in your library version's MetadataUpdateType enum.

Example fix

// before (older Iceberg that lacks ADD_ENCRYPTION_KEY handling)
MetadataUpdateParser.toJson(update, generator); // throws for ADD_ENCRYPTION_KEY
// after (upgrade Iceberg so the switch includes the case)
case ADD_ENCRYPTION_KEY:
  writeAddEncryptionKey((MetadataUpdate.AddEncryptionKey) update, generator);
  break;

// pre-validate: confirm the update's action exists in your version's MetadataUpdateType enum
MetadataUpdateType action = MetadataUpdateType.valueOf(update.getClass());

try {
  MetadataUpdateParser.toJson(update, generator);
} catch (IllegalArgumentException e) {
  if (!e.getMessage().contains("Unrecognized action")) throw e;
  LOG.warn("Skipping unsupported metadata update action", e);
}

When it happens

Trigger: Calling MetadataUpdateParser.toJson on a MetadataUpdate whose MetadataUpdateType is not handled in the switch (e.g. a custom update or one introduced in a newer library version than the parser code).

Common situations: Running an older Iceberg client against metadata produced by a newer server/writer that emits new update actions; patched builds adding new update types without updating MetadataUpdateParser.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Cannot convert metadata update action to json
• 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/5175997aa08bc040. Report an issue: GitHub.

Appendix: source

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

        break;
      case SET_CURRENT_VIEW_VERSION:
        writeSetCurrentViewVersionId(
            (MetadataUpdate.SetCurrentViewVersion) metadataUpdate, generator);
        break;
      case REMOVE_PARTITION_SPECS:
        writeRemovePartitionSpecs((MetadataUpdate.RemovePartitionSpecs) metadataUpdate, generator);
        break;
      case REMOVE_SCHEMAS:
        writeRemoveSchemas((MetadataUpdate.RemoveSchemas) metadataUpdate, generator);
        break;
      case ADD_ENCRYPTION_KEY:
        writeAddEncryptionKey((MetadataUpdate.AddEncryptionKey) metadataUpdate, generator);
        break;
      case REMOVE_ENCRYPTION_KEY:
        writeRemoveEncryptionKey((MetadataUpdate.RemoveEncryptionKey) metadataUpdate, generator);
        break;
      default:
        throw new IllegalArgumentException(
            String.format(
                "Cannot convert metadata update to json. Unrecognized action: %s", updateAction));
    }

    generator.writeEndObject();
  }

  /**
   * Read MetadataUpdate from a JSON string.
   *
   * @param json a JSON string of a MetadataUpdate
   * @return a MetadataUpdate object
   */
  public static MetadataUpdate fromJson(String json) {
    return JsonUtil.parse(json, MetadataUpdateParser::fromJson);
  }

  public static MetadataUpdate fromJson(JsonNode jsonNode) {

View on GitHub (pinned to 86d9c8fc54)