apache/iceberg · error · IllegalArgumentException

Property ' ' has been deprecated and will be removed in…

Error message

Property '%s' has been deprecated and will be removed in 2.0.0, use '%s' instead.

What it means

getAndCheckLegacyLocation rejects table properties that are deprecated: if a deprecated key (e.g., object.store.path) still has a value, it throws immediately instead of silently honoring it, directing users to the replacement property before the 2.0.0 removal.

Solutions

1. Remove the deprecated property from table properties and set the modern replacement (e.g., use the current write.data.path / storage location properties)
2. Migrate stored data locations if needed before deleting the property
3. Update tooling/templates to write the new property names

Example fix

// before
table.updateProperties().set("object.store.path", "s3://bucket/base").commit();
// after
table.updateProperties().set(TableProperties.WRITE_DATA_LOCATION, "s3://bucket/base").commit();

if (props.get("object.store.path") != null) {
  throw new IllegalStateException("Remove deprecated 'object.store.path'; use the current write location property");
}

try {
  LocationProviders.locationsFor(location, props);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("deprecated")) { /* migrate property then retry */ }
  else throw e;
}

When it happens

Trigger: A table still carries a value for a deprecated property in DEPRECATED_PROPERTIES (e.g., object.store.path, write.folder-storage.location style keys) while Iceberg resolves location providers.

Common situations: Tables upgraded from older Iceberg versions keeping stale properties; migration scripts copying old table properties; setting the old key from an outdated tutorial or tooling.

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

• apply(value) is deprecated, use bind(Type).apply(value)
• apply(value) is deprecated, use bind(Type).apply(value)
• Counter is not supported.
• Invalid file format
• Invalid isolation level

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/LocationProviders.java:88

    } else if (PropertyUtil.propertyAsBoolean(
        properties,
        TableProperties.OBJECT_STORE_ENABLED,
        TableProperties.OBJECT_STORE_ENABLED_DEFAULT)) {
      return new ObjectStoreLocationProvider(location, properties);
    } else {
      return new DefaultLocationProvider(location, properties);
    }
  }

  private static final Set<String> DEPRECATED_PROPERTIES =
      ImmutableSet.of(
          TableProperties.OBJECT_STORE_PATH, TableProperties.WRITE_FOLDER_STORAGE_LOCATION);

  private static String getAndCheckLegacyLocation(Map<String, String> properties, String key) {
    String value = properties.get(key);

    if (value != null && DEPRECATED_PROPERTIES.contains(key)) {
      throw new IllegalArgumentException(
          String.format(
              "Property '%s' has been deprecated and will be removed in 2.0.0, use '%s' instead.",
              key, TableProperties.WRITE_DATA_LOCATION));
    }

    return value;
  }

  static class DefaultLocationProvider implements LocationProvider {
    private final String dataLocation;

    DefaultLocationProvider(String tableLocation, Map<String, String> properties) {
      this.dataLocation = LocationUtil.stripTrailingSlash(dataLocation(properties, tableLocation));
    }

    private static String dataLocation(Map<String, String> properties, String tableLocation) {
      String dataLocation =
          getAndCheckLegacyLocation(properties, TableProperties.WRITE_DATA_LOCATION);

View on GitHub (pinned to 86d9c8fc54)