apache/iceberg · error · IllegalArgumentException

Cannot initialize LockManager

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.

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 LockManager, missing no-arg constructor
• Cannot initialize MetricsReporter
• Cannot initialize AdlsTokenCredentialProvider
• Cannot initialize AliyunClientFactory
• Cannot initialize AuthManager

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

Appendix: 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)