apache/iceberg · error · IllegalArgumentException

Cannot initialize LockManager, %s does not implement LockMan

Error message

Cannot initialize LockManager, %s does not implement LockManager.

What it means

After reflectively constructing the configured class, LockManagers.loadLockManager verifies the instance implements LockManager; a ClassCastException from DynConstructors is rethrown as IllegalArgumentException stating the class does not implement LockManager. The configured 'lock.impl' class was loadable but has the wrong type.

Source

Thrown at core/src/main/java/org/apache/iceberg/util/LockManagers.java:70

    } else {
      return defaultLockManager();
    }
  }

  private static LockManager loadLockManager(String impl, Map<String, String> properties) {
    DynConstructors.Ctor<LockManager> ctor;
    try {
      ctor = DynConstructors.builder(LockManager.class).hiddenImpl(impl).buildChecked();
    } catch (NoSuchMethodException e) {
      throw new IllegalArgumentException(
          String.format("Cannot initialize LockManager, missing no-arg constructor: %s", impl), e);
    }

    LockManager lockManager;
    try {
      lockManager = ctor.newInstance();
    } catch (ClassCastException e) {
      throw new IllegalArgumentException(
          String.format("Cannot initialize LockManager, %s does not implement LockManager.", impl),
          e);
    }

    lockManager.initialize(properties);
    return lockManager;
  }

  public abstract static class BaseLockManager implements LockManager {

    private static volatile ScheduledExecutorService scheduler;

    private long acquireTimeoutMs;
    private long acquireIntervalMs;
    private long heartbeatIntervalMs;
    private long heartbeatTimeoutMs;
    private int heartbeatThreads;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set lock.impl to the fully-qualified name of a class implementing org.apache.iceberg.util.LockManager
2. Check that the class name is not accidentally resolving to a different class (print Class.forName result)
3. Ensure the JAR containing the LockManager implementation is on the runtime classpath and compatible

Example fix

// before
properties.put("lock.impl", "com.example.MyLockManagerImpl$Builder");
// after
properties.put("lock.impl", "com.example.MyLockManagerImpl");

Class<?> c = Class.forName(impl);
if (!LockManager.class.isAssignableFrom(c)) throw new IllegalArgumentException(impl + " does not implement LockManager");

boolean isLockManagerImpl = LockManager.class.isAssignableFrom(Class.forName(impl));

try { LockManagers.from(properties); } catch (IllegalArgumentException e) { if (e.getMessage().contains("does not implement")) { properties.put("lock.impl", "org.apache.iceberg.util.BaseLockManager"); } throw e; }

When it happens

Trigger: Setting lock.impl to a class that is not a LockManager (e.g., an unrelated utility class, or a similar-named class from a different library).

Common situations: Typos in the fully-qualified class name that accidentally match another class; passing a factory or builder class instead of the manager itself; classloader conflicts loading an old/incompatible version of the intended implementation.

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

• Cannot initialize MetricsReporter, %s does not implement Met
• Cannot initialize LockManager, missing no-arg constructor: %
• Cannot initialize AliyunClientFactory, %s does not implement
• Cannot initialize AdlsTokenCredentialProvider, %s does not i
• Cannot initialize Catalog, %s does not implement Catalog.

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