apache/iceberg · error · BadConfigurationException

Class %s 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.

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)

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

• Unable to find a constructor for implementation %s of %s. Ma
• Cannot initialize TLSConfigurer implementation %s: %s
• Cannot initialize AliyunClientFactory, missing no-arg constr
• Cannot initialize AwsClientFactory, missing no-arg construct
• Cannot initialize AwsClientFactory, %s does not implement Aw

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