apache/hadoop · error · IllegalArgumentException

Failed to instantiate comparator: {comparator}({e})

Error message

Failed to instantiate comparator: {comparator}({e})

What it means

IllegalArgumentException from makeComparator wrapping any failure while resolving the jclass comparator: Class.forName, the RawComparator cast (asSubclass), getDeclaredConstructor(), or newInstance(). The original exception's toString() is embedded in the message, so the cause is directly readable. Preconditions to meet: class on the classpath, public no-arg constructor, implements RawComparator.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java:2117

            TFILE_COMPARATOR_JCLASS_ENABLED_DEFAULT)) {
          throw new IllegalArgumentException(
              "Class-name comparators are not enabled (set "
                  + TFILE_COMPARATOR_JCLASS_ENABLED + "=true to allow): "
                  + comparator);
        }
        String compClassName =
            comparator.substring(COMPARATOR_JCLASS.length()).trim();
        try {
          // Resolve without running the class initializer, confirm it really
          // is a RawComparator, and only then load and construct it.
          Class<?> compClass =
              Class.forName(compClassName, false, conf.getClassLoader());
          RawComparator<Object> rawComparator =
              (RawComparator<Object>) compClass.asSubclass(RawComparator.class)
                  .getDeclaredConstructor().newInstance();
          return new BytesComparator(rawComparator);
        } catch (Exception e) {
          throw new IllegalArgumentException(
              "Failed to instantiate comparator: " + comparator + "("
                  + e.toString() + ")");
        }
      } else {
        throw new IllegalArgumentException("Unsupported comparator: "
            + comparator);
      }
    }

    public void write(DataOutput out) throws IOException {
      TFile.API_VERSION.write(out);
      Utils.writeVLong(out, recordCount);
      Utils.writeString(out, strComparator);
    }

    public long getRecordCount() {
      return recordCount;
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Read the parenthesized cause in the message: ClassNotFoundException -> ship the class; NoSuchMethodException -> add public no-arg ctor; ClassCastException -> implement RawComparator.
2. Ship the exact comparator class in the job jar and keep the class name stable across versions of your code.
3. If the ctor fails for environment reasons, fix that environment issue; the guard rethrows whatever the ctor threw.

Example fix

// before
public class MyKeyComparator implements RawComparator<MyKey> {
  public MyKeyComparator(MyKey proto) {} // no no-arg ctor -> always fails
}
// after
public class MyKeyComparator implements RawComparator<MyKey> {
  public MyKeyComparator() {} // required: public, zero-arg
  // ... compare(...) methods
}

String cmpName = readerOrWriterComparatorName;
if (cmpName != null && cmpName.startsWith("jclass:")) {
  Class<?> c = Class.forName(cmpName.substring("jclass:".length()).trim(), false, conf.getClassLoader());
  c.asSubclass(org.apache.hadoop.io.RawComparator.class).getDeclaredConstructor(); // throws early with a clear cause
}

try {
  ...open writer/reader...
} catch (IllegalArgumentException e) {
  // e.getMessage() embeds the root cause; fix classpath/ctor, then retry with a NEW reader
}

When it happens

Trigger: Comparator class missing from the reader's classpath (client job jar doesn't ship it), the class lacks a public no-arg constructor, it does not implement RawComparator, or its constructor throws. Note forName is called with initialize=false, so static-initializer side effects are avoided but instance construction errors still land here.

Common situations: Job jars that ship the writer's comparator but not the reader's, refactoring that renamed or moved the comparator class without regenerating TFiles, comparators with only constructor-arg constructors, or comparators whose ctor throws in restricted environments.

Related errors

• Class-name comparators are not enabled (set tfile.comparator
• Unsupported comparator: {comparator}
• Errors on getting mount table loader class. The fs.viewfs.mo
• Cannot initialize the class: {clazz}
• key out of order: {key} after {lastKey}

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