apache/hadoop · error · HdfsCompatIllegalArgumentException

class name " + suiteClassName + " must be an implementation

Error message

class name " + suiteClassName + " must be an implementation of " + HdfsCompatSuite.class.getName()

What it means

After loading the class named by hadoop.compatibility.suite.<name>.classname, initSuite requires the constructed object to implement HdfsCompatSuite. Note a defect in this code path: it reflects on suiteClassName.getClass() — the Class of the java.lang.String value — and instantiates a new String, so the instanceof check can never succeed for a custom suite in this version. The intended behavior (Class.forName(suiteClassName) + no-arg constructor + instanceof) is what the message describes.

Source

Thrown at hadoop-tools/hadoop-compat-bench/src/main/java/org/apache/hadoop/fs/compat/common/HdfsCompatCommand.java:88

    Map<String, HdfsCompatSuite> defaultSuites = getDefaultSuites();
    this.suite = defaultSuites.getOrDefault(this.suiteName, null);
    if (this.suite != null) {
      return;
    }
    String key = "hadoop.compatibility.suite." + this.suiteName + ".classname";
    final String suiteClassName = conf.get(key, null);
    if ((suiteClassName == null) || suiteClassName.isEmpty()) {
      throw new HdfsCompatIllegalArgumentException(
          "cannot get class name for suite " + this.suiteName +
              ", configuration " + key + " is not properly set.");
    }
    Constructor<?> ctor = suiteClassName.getClass().getConstructor();
    ctor.setAccessible(true);
    Object suiteObj = ctor.newInstance();
    if (suiteObj instanceof HdfsCompatSuite) {
      this.suite = (HdfsCompatSuite) suiteObj;
    } else {
      throw new HdfsCompatIllegalArgumentException(
          "class name " + suiteClassName + " must be an" +
              " implementation of " + HdfsCompatSuite.class.getName());
    }
    if (suite.getSuiteName() == null || suite.getSuiteName().isEmpty()) {
      throw new HdfsCompatIllegalArgumentException(
          "suite " + suiteClassName + " suiteName is empty");
    }
    for (HdfsCompatSuite defaultSuite : defaultSuites.values()) {
      if (suite.getSuiteName().equalsIgnoreCase(defaultSuite.getSuiteName())) {
        throw new HdfsCompatIllegalArgumentException(
            "suite " + suiteClassName + " suiteName" +
                " conflicts with default suite " + defaultSuite.getSuiteName());
      }
    }
    if (!hasApiCase() && !hasShellCase()) {
      throw new HdfsCompatIllegalArgumentException(
          "suite " + suiteClassName + " is empty for both API and SHELL");
    }

View on GitHub (pinned to 2add963021)

Solutions

Verify the configured class implements org.apache.hadoop.fs.compat.common.HdfsCompatSuite and has a public no-arg constructor
If you build this module from source, fix the instantiation: use Class.forName(suiteClassName).getConstructor() instead of suiteClassName.getClass().getConstructor()
Check the FQCN in the configuration value for typos
Track/upgrade to a release where custom-suite loading is fixed

Example fix

// before: reflects on String.class, so suiteObj is a String
// -> always "class name ... must be an implementation of ...HdfsCompatSuite"
Constructor<?> ctor = suiteClassName.getClass().getConstructor();
Object suiteObj = ctor.newInstance();

// after
Class<?> clazz = Class.forName(suiteClassName);
Constructor<?> ctor = clazz.getConstructor();
Object suiteObj = ctor.newInstance();

Defensive patterns

Strategy: try-catch

Validate before calling

String className = conf.get(key);
Class<?> c = Class.forName(className);
if (!HdfsCompatSuite.class.isAssignableFrom(c)
    || !Modifier.isPublic(c.getModifiers())) {
  throw new IllegalArgumentException(
      className + " must be a public implementation of HdfsCompatSuite");
}
c.getConstructor(); // NoSuchMethodException -> fail fast on missing no-arg ctor

Type guard

static boolean isCompatSuiteClass(Class<?> c) {
  return HdfsCompatSuite.class.isAssignableFrom(c);
}

Try / catch

Catch HdfsCompatIllegalArgumentException around the tool invocation; on 'must be an implementation of', verify the configured class implements HdfsCompatSuite — and note this Hadoop version's getClass()-on-String defect makes every custom suite fail here, so patch or pin a fixed build before retrying.

Prevention

Unit-test custom suites by loading them reflectively exactly the way HdfsCompatCommand does
Verify assignability with HdfsCompatSuite.class.isAssignableFrom(clazz) at registration time
Pin a Hadoop version where custom-suite loading is verified, or run the bench from a patched source tree

When it happens

Trigger: Configuring a class that does not implement HdfsCompatSuite; or, with the current implementation, configuring any class at all, because the reflective load resolves against String.class and produces an object that always fails the instanceof check (then this exact error is thrown).

Common situations: First run after registering a custom suite (hits the getClass() defect); class renamed so an old FQCN no longer names a suite implementation; copy-paste of the class name with a typo.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/1266e07c5ba76f40. Report an issue: GitHub.