apache/iceberg · warning

Fallback ID assignment in Parquet is UNSAFE and will be…

Error message

Fallback ID assignment in Parquet is UNSAFE and will be removed in 2.0.0. Use name mapping instead.

What it means

The Netlify/Netflix-specific fallback config iceberg.netflix.unsafe-parquet-id-fallback.enabled assigns Parquet column IDs by field name/position when no name mapping exists, which is unsafe. Logging this warning signals the fallback is active and that the mechanism will be removed in Iceberg 2.0.0; users should migrate to name mapping. The default is true, so legacy pipelines see this warning on read paths using this config entry.

Solutions

1. Ensure a name mapping exists for the table (set schema.name-mapping.default) so ID resolution does not need the fallback.
2. Rewrite affected Parquet files so they embed proper field IDs.
3. Set iceberg.netflix.unsafe-parquet-id-fallback.enabled=false to confirm nothing depends on the fallback, then keep it off.
4. Plan migration before upgrading to 2.0.0 where this fallback is removed.

Example fix

// before
// table has no name mapping; fallback silently used
Table table = catalog.loadTable(identifier);
// after
Table table = catalog.loadTable(identifier);
table.updateProperties().set("schema.name-mapping.default", NameMappingParser.toJson(
    MappingsGenerator.generate(table.schema()))).commit(); // explicit mapping instead of unsafe fallback

String mapping = table.properties().get("schema.name-mapping.default");
if (mapping == null) {
  throw new IllegalStateException("Set schema.name-mapping.default before relying on Parquet ID fallback");
}

When it happens

Trigger: Reading/writing Parquet files where field IDs cannot be resolved from a name mapping and the config iceberg.netflix.unsafe-parquet-id-fallback.enabled is consulted (default true); the parse function logs the warning each time the config value is parsed.

Common situations: Legacy tables written before name mappings were introduced; reading Parquet files produced by external writers that omit field IDs; migrations from older Netflix/internal pipelines; planning ahead for the 2.0.0 removal.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Class was not found
• Inferring = since property was provided. Please explicitly…
• Skipping bloom filter config for missing field
• Skipping column statistics config for missing field
• Skipping dictionary encoding config for missing field

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/SystemConfigs.java:93

   */
  public static final ConfigEntry<Integer> IO_MANIFEST_CACHE_MAX_FILEIO =
      new ConfigEntry<>(
          "iceberg.io.manifest.cache.fileio-max",
          "ICEBERG_IO_MANIFEST_CACHE_FILEIO_MAX",
          8,
          Integer::parseUnsignedInt);

  /**
   * @deprecated will be removed in 2.0.0; use name mapping instead
   */
  @Deprecated
  public static final ConfigEntry<Boolean> NETFLIX_UNSAFE_PARQUET_ID_FALLBACK_ENABLED =
      new ConfigEntry<>(
          "iceberg.netflix.unsafe-parquet-id-fallback.enabled",
          "ICEBERG_NETFLIX_UNSAFE_PARQUET_ID_FALLBACK_ENABLED",
          true,
          s -> {
            LOG.warn(
                "Fallback ID assignment in Parquet is UNSAFE and will be removed in 2.0.0. Use name mapping instead.");
            return Boolean.parseBoolean(s);
          });

  public static class ConfigEntry<T> {
    private final String propertyKey;
    private final String envKey;
    private final T defaultValue;
    private final Function<String, T> parseFunc;
    private T lazyValue = null;

    private ConfigEntry(
        String propertyKey, String envKey, T defaultValue, Function<String, T> parseFunc) {
      this.propertyKey = propertyKey;
      this.envKey = envKey;
      this.defaultValue = defaultValue;
      this.parseFunc = parseFunc;
    }

View on GitHub (pinned to 86d9c8fc54)