apache/iceberg · warning

Failed to update external schema mapping

Error message

Failed to update external schema mapping: {}

What it means

After a schema update, SchemaUpdate tries to regenerate the internal name mapping stored in table property 'schema.name-mapping.default'. If building or serializing the updated mapping fails, this warning is logged and the update proceeds without refreshing the mapping rather than failing the whole schema change.

Solutions

1. Inspect and fix or remove the 'schema.name-mapping.default' table property, then re-apply the schema update.
2. Regenerate the name mapping with NameMappingParser/NameMapping.create(schema) and set it explicitly.
3. Ignore if the external mapping is intentionally managed elsewhere; consumers will use the stale mapping.

Example fix

// before
table.updateSchema().addColumn("new_col", Types.LongType.get()).commit(); // warns, stale mapping
// after
table.updateProperties().set(TableProperties.DEFAULT_NAME_MAPPING, NameMappingParser.toJson(NameMapping.create(table.schema()))).commit();

String mapping = table.properties().get("schema.name-mapping.default");
if (mapping != null) NameMappingParser.fromJson(mapping); // throws if corrupt

try { schemaUpdate.commit(); } catch (RuntimeException e) { /* real failures propagate; mapping warnings are logged not thrown */ }

When it happens

Trigger: committing a schema update (addColumn, renameColumn, etc.) on a table whose name-mapping JSON is corrupt, incompatible, or whose mapping reconstruction throws a RuntimeException, then calling update()/commit().

Common situations: Manually edited or truncated schema.name-mapping.default property, mappings written by older/other tools, corrupted metadata after failed writes.

Related errors

• ORC schema does not contain Iceberg IDs
• Can't convert unknown type
• Cannot add column since setting default values in Spark is…
• Cannot add column since setting default values in Spark is…
• Cannot add fields to map keys:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/SchemaUpdate.java:503

    String mappingJson = metadata.property(TableProperties.DEFAULT_NAME_MAPPING, null);
    TableMetadata newMetadata = metadata;
    if (mappingJson != null) {
      try {
        // parse and update the mapping
        NameMapping mapping = NameMappingParser.fromJson(mappingJson);
        NameMapping updated = MappingUtil.update(mapping, updates, parentToAddedIds);

        // replace the table property
        Map<String, String> updatedProperties = Maps.newHashMap();
        updatedProperties.putAll(metadata.properties());
        updatedProperties.put(
            TableProperties.DEFAULT_NAME_MAPPING, NameMappingParser.toJson(updated));

        newMetadata = metadata.replaceProperties(updatedProperties);

      } catch (RuntimeException e) {
        // log the error, but do not fail the update
        LOG.warn("Failed to update external schema mapping: {}", mappingJson, e);
      }
    }

    // Transform the metrics if they exist
    if (base != null && base.properties() != null) {
      Schema newSchema = newMetadata.schema();
      List<String> deletedColumns =
          deletes.stream().map(schema::findColumnName).collect(Collectors.toList());
      Map<String, String> renamedColumns =
          updates.keySet().stream()
              .filter(id -> !addedNameToId.containsValue(id)) // remove added columns
              .filter(id -> !schema.findColumnName(id).equals(newSchema.findColumnName(id)))
              .collect(Collectors.toMap(schema::findColumnName, newSchema::findColumnName));
      if (!deletedColumns.isEmpty() || !renamedColumns.isEmpty()) {
        Set<String> columnProperties =
            ImmutableSet.of(
                TableProperties.METRICS_MODE_COLUMN_CONF_PREFIX,
                TableProperties.PARQUET_BLOOM_FILTER_COLUMN_ENABLED_PREFIX,

View on GitHub (pinned to 86d9c8fc54)