apache/iceberg · error · BadConfigurationException

Class was not found

Error message

Class %s was not found

What it means

Thrown when a Parquet compression codec class configured via the codec class-name property cannot be loaded by the configuration's class loader. The factory resolves codec classes reflectively (Hadoop CompressionCodec); if loadClass fails with ClassNotFoundException it wraps it in BadConfigurationException. This indicates the codec class name is wrong or the codec's JAR is not on the classpath.

Solutions

1. Fix the codec class name to a fully-qualified existing CompressionCodec class (e.g. org.apache.hadoop.io.compress.ZstdCodec).
2. Add the JAR containing the codec to the runtime classpath of the job/driver and executors.
3. Fall back to a built-in codec (snappy, gzip, zstd) that ships with the distribution.
4. Verify the class is visible to the configuration's classLoader (check fat-jar shading/relocation).

Example fix

// before
conf.set("write.parquet.compression-codec", "zstandard");
// after
conf.set("write.parquet.compression-codec", "org.apache.hadoop.io.compress.ZstdCodec");

String cls = conf.get("write.parquet.compression-codec");
if (cls != null) {
  try {
    Class<?> c = Class.forName(cls, true, Thread.currentThread().getContextClassLoader());
    if (!org.apache.hadoop.io.compress.CompressionCodec.class.isAssignableFrom(c)) {
      throw new IllegalArgumentException(cls + " is not a CompressionCodec");
    }
  } catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Codec class not on classpath: " + cls, e);
  }
}

try {
  codec = ParquetCodecFactory.getCodec(conf, name, level);
} catch (BadConfigurationException e) {
  LOG.warn("Codec unavailable, falling back to SNAPPY", e);
  codec = ParquetCodecFactory.getCodec(conf, "snappy", null);
}

When it happens

Trigger: Calling getCodec with a codec class name string that is misspelled, not a Hadoop CompressionCodec implementation, or whose JAR is absent from the classpath; also when a custom codec plugin was removed or the shaded/deployment JAR excludes it.

Common situations: Typo in table property like write.parquet.compression-codec or Hadoop io.compression.codecs; deploying a slim runtime image missing hadoop-codec JARs (e.g. zstd/brotli implementations); switching clusters where custom codecs are not installed.

Related errors

• Cannot initialize TLSConfigurer implementation
• Unable to find a constructor for implementation
• Cannot create to generate and configure the client SDK…
• Cannot find class; alternatives
• Cannot find constructor for

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetCodecFactory.java:67

    String cacheKey = cacheKey(codecName);
    CompressionCodec codec = CODEC_BY_NAME.get(cacheKey);
    if (codec != null) {
      return codec;
    }

    try {
      Class<?> codecClass;
      try {
        codecClass = Class.forName(codecClassName);
      } catch (ClassNotFoundException e) {
        // Try to load the class using the job classloader
        codecClass = configuration.getClassLoader().loadClass(codecClassName);
      }
      codec = (CompressionCodec) ReflectionUtils.newInstance(codecClass, configuration);
      CODEC_BY_NAME.put(cacheKey, codec);
      return codec;
    } catch (ClassNotFoundException e) {
      throw new BadConfigurationException("Class " + codecClassName + " was not found", e);
    }
  }

  @SuppressWarnings("deprecation")
  private String cacheKey(CompressionCodecName codecName) {
    String level = null;
    switch (codecName) {
      case GZIP:
        level = configuration.get("zlib.compress.level");
        break;
      case BROTLI:
        level = configuration.get("compression.brotli.quality");
        break;
      case ZSTD:
        level = configuration.get("parquet.compression.codec.zstd.level");
        if (level == null) {
          // keep "io.compression.codec.zstd.level" for backwards compatibility
          level = configuration.get("io.compression.codec.zstd.level");

View on GitHub (pinned to 86d9c8fc54)