apache/iceberg · error · IllegalArgumentException

Provided implementation for dynamic instantiation should imp

Error message

Provided implementation for dynamic instantiation should implement %s.

What it means

After reflective construction, the instantiated object is cast to LocationProvider; a ClassCastException means the configured class loaded and constructed but does not implement LocationProvider, so locationsFor rejects it with this IllegalArgumentException.

Source

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

        ctor =
            DynConstructors.builder(LocationProvider.class)
                .impl(impl, String.class, Map.class)
                .impl(impl)
                .buildChecked(); // fall back to no-arg constructor
      } catch (NoSuchMethodException e) {
        throw new IllegalArgumentException(
            String.format(
                "Unable to find a constructor for implementation %s of %s. "
                    + "Make sure the implementation is in classpath, and that it either "
                    + "has a public no-arg constructor or a two-arg constructor "
                    + "taking in the string base table location and its property string map.",
                impl, LocationProvider.class),
            e);
      }
      try {
        return ctor.newInstance(location, properties);
      } catch (ClassCastException e) {
        throw new IllegalArgumentException(
            String.format(
                "Provided implementation for dynamic instantiation should implement %s.",
                LocationProvider.class),
            e);
      }
    } 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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Make the configured class implement org.apache.iceberg.LocationProvider
Rebuild against the Iceberg version in use so the interface matches
Point write.location-provider.impl at a built-in provider or a correct custom implementation

Example fix

// before
class MyProvider { public MyProvider(String l, Map<String,String> p) {} }
// after
class MyProvider implements LocationProvider {
  public MyProvider(String location, Map<String, String> properties) { ... }
  @Override public String newDataLocation(String fileName) { ... }
}

Defensive patterns

Strategy: type-guard

Validate before calling

Class<?> c = Class.forName(implName);
if (!LocationProvider.class.isAssignableFrom(c)) {
  throw new IllegalStateException(implName + " must implement LocationProvider");
}

Type guard

LocationProvider.class.isAssignableFrom(clazz)

Try / catch

try {
  LocationProviders.locationsFor(location, props);
} catch (IllegalArgumentException e) {
  LOG.error("Impl does not implement LocationProvider: {}", implName, e);
}

Prevention

Compile custom providers against the same Iceberg version in production
Implement org.apache.iceberg.LocationProvider explicitly
Run a smoke test instantiating the provider before deploying

When it happens

Trigger: Setting write.location-provider.impl to a class that constructs successfully via a matching constructor signature but does not implement org.apache.iceberg.view.LocationProvider/org.apache.iceberg.LocationProvider (e.g., implements a different interface or none).

Common situations: Copying a provider implementation from another library or older Iceberg version with a different interface; generic-purpose class reused accidentally as location provider.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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