{"record":{"id":"5b0b0ec2712a1096","repo":"apache/iceberg","slug":"failed-to-update-external-schema-mapping","errorCode":null,"errorMessage":"Failed to update external schema mapping: {}","messagePattern":"Failed to update external schema mapping: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/apache/iceberg/SchemaUpdate.java","lineNumber":503,"sourceCode":"    String mappingJson = metadata.property(TableProperties.DEFAULT_NAME_MAPPING, null);\n    TableMetadata newMetadata = metadata;\n    if (mappingJson != null) {\n      try {\n        // parse and update the mapping\n        NameMapping mapping = NameMappingParser.fromJson(mappingJson);\n        NameMapping updated = MappingUtil.update(mapping, updates, parentToAddedIds);\n\n        // replace the table property\n        Map<String, String> updatedProperties = Maps.newHashMap();\n        updatedProperties.putAll(metadata.properties());\n        updatedProperties.put(\n            TableProperties.DEFAULT_NAME_MAPPING, NameMappingParser.toJson(updated));\n\n        newMetadata = metadata.replaceProperties(updatedProperties);\n\n      } catch (RuntimeException e) {\n        // log the error, but do not fail the update\n        LOG.warn(\"Failed to update external schema mapping: {}\", mappingJson, e);\n      }\n    }\n\n    // Transform the metrics if they exist\n    if (base != null && base.properties() != null) {\n      Schema newSchema = newMetadata.schema();\n      List<String> deletedColumns =\n          deletes.stream().map(schema::findColumnName).collect(Collectors.toList());\n      Map<String, String> renamedColumns =\n          updates.keySet().stream()\n              .filter(id -> !addedNameToId.containsValue(id)) // remove added columns\n              .filter(id -> !schema.findColumnName(id).equals(newSchema.findColumnName(id)))\n              .collect(Collectors.toMap(schema::findColumnName, newSchema::findColumnName));\n      if (!deletedColumns.isEmpty() || !renamedColumns.isEmpty()) {\n        Set<String> columnProperties =\n            ImmutableSet.of(\n                TableProperties.METRICS_MODE_COLUMN_CONF_PREFIX,\n                TableProperties.PARQUET_BLOOM_FILTER_COLUMN_ENABLED_PREFIX,","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/SchemaUpdate.java#L485-L521","documentation":"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.","triggerScenarios":"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().","commonSituations":"Manually edited or truncated schema.name-mapping.default property, mappings written by older/other tools, corrupted metadata after failed writes.","solutions":["Inspect and fix or remove the 'schema.name-mapping.default' table property, then re-apply the schema update.","Regenerate the name mapping with NameMappingParser/NameMapping.create(schema) and set it explicitly.","Ignore if the external mapping is intentionally managed elsewhere; consumers will use the stale mapping."],"exampleFix":"// before\ntable.updateSchema().addColumn(\"new_col\", Types.LongType.get()).commit(); // warns, stale mapping\n// after\ntable.updateProperties().set(TableProperties.DEFAULT_NAME_MAPPING, NameMappingParser.toJson(NameMapping.create(table.schema()))).commit();","handlingStrategy":"validation","validationCode":"String mapping = table.properties().get(\"schema.name-mapping.default\");\nif (mapping != null) NameMappingParser.fromJson(mapping); // throws if corrupt","typeGuard":null,"tryCatchPattern":"try { schemaUpdate.commit(); } catch (RuntimeException e) { /* real failures propagate; mapping warnings are logged not thrown */ }","preventionTips":["Do not hand-edit schema.name-mapping.default","Regenerate mapping after schema changes if consumers depend on it","Verify existing mapping parses before committing schema updates"],"tags":["schema","name-mapping","metadata"],"backgroundTag":"unexpected-response-shape","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}