apache/hadoop · error · UnknownCipherSuiteException

No configuration found for the cipher suite {} prefixed with

Error message

No configuration found for the cipher suite {} prefixed with hadoop.security.crypto.codec.classes. Please see the example configuration hadoop.security.crypto.codec.classes.EXAMPLECIPHERSUITE at core-default.xml for details.

What it means

After resolving a known CipherSuite, HdfsKMSUtil asks CryptoCodec.getInstance(conf, suite) for a codec implementation; if it returns null, no class is configured for the hadoop.security.crypto.codec.classes.<suffix> key matching the suite, and an UnknownCipherSuiteException with this message is thrown. Stock core-default.xml ships JceAesCtrCryptoCodec/OpensslAesCtrCryptoCodec for the default suites, so the usual root cause is a stripped or absent core-default.xml on the client classpath.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/HdfsKMSUtil.java:112

   * Obtain a CryptoCodec based on the CipherSuite set in a FileEncryptionInfo
   * and the available CryptoCodecs configured in the Configuration.
   *
   * @param conf   Configuration
   * @param feInfo FileEncryptionInfo
   * @return CryptoCodec
   * @throws IOException if no suitable CryptoCodec for the CipherSuite is
   *                     available.
   */
  public static CryptoCodec getCryptoCodec(Configuration conf,
      FileEncryptionInfo feInfo) throws IOException {
    final CipherSuite suite = feInfo.getCipherSuite();
    if (suite.equals(CipherSuite.UNKNOWN)) {
      throw new IOException("NameNode specified unknown CipherSuite with ID "
          + suite.getUnknownValue() + ", cannot instantiate CryptoCodec.");
    }
    final CryptoCodec codec = CryptoCodec.getInstance(conf, suite);
    if (codec == null) {
      throw new UnknownCipherSuiteException(
          "No configuration found for the cipher suite "
              + suite.getConfigSuffix() + " prefixed with "
              + HADOOP_SECURITY_CRYPTO_CODEC_CLASSES_KEY_PREFIX
              + ". Please see the example configuration "
              + "hadoop.security.crypto.codec.classes.EXAMPLECIPHERSUITE "
              + "at core-default.xml for details.");
    }
    return codec;
  }

  /**
   * The key provider uri is searched in the following order.
   * 1. If there is a mapping in Credential's secrets map for namenode uri.
   * 2. From namenode getServerDefaults call.
   * 3. Finally fallback to local conf.
   * @return keyProviderUri if found from either of above 3 cases,
   * null otherwise
   * @throws IOException

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure core-default.xml is on the classpath (addResource or keep defaults loaded) so the built-in codec entries are visible
2. Explicitly set the codec property, e.g. hadoop.security.crypto.codec.classes.aes.ctr.nopadding = org.apache.hadoop.crypto.JceAesCtrCryptoCodec,org.apache.hadoop.crypto.OpensslAesCtrCryptoCodec
3. Verify the JCE/OpenSSL providers actually load (JceAesCtrCryptoCodec requires JDK JCE; the OpenSSL variant requires libcrypto) — misconfigured SSL natives can make getInstance return null

Example fix

<!-- before: no codec mapping visible -->
<configuration><!-- nothing for crypto codecs --></configuration>

<!-- after -->
<property>
  <name>hadoop.security.crypto.codec.classes.aes.ctr.nopadding</name>
  <value>org.apache.hadoop.crypto.JceAesCtrCryptoCodec,org.apache.hadoop.crypto.OpensslAesCtrCryptoCodec</value>
</property>

// Fail fast if the codec mapping for the default suite is missing:
String key = "hadoop.security.crypto.codec.classes"
    + CipherSuite.AES_CTR_NOPADDING.getConfigSuffix();
if (conf.get(key) == null && !conf.getBoolean("fs.hdfs.impl.disable.cache", false)) {
  conf.set(key, "org.apache.hadoop.crypto.JceAesCtrCryptoCodec,"
      + "org.apache.hadoop.crypto.OpensslAesCtrCryptoCodec");
}

try {
  return HdfsKMSUtil.getCryptoCodec(conf, feInfo);
} catch (UnknownCipherSuiteException e) {
  // add core-default.xml / explicit codec classes, then retry once
  conf.addResource("core-default.xml");
  return HdfsKMSUtil.getCryptoCodec(conf, feInfo);
}

When it happens

Trigger: Reading an encryption-zone file with a Configuration that lacks the codec mapping: custom minimal core-site.xml without core-default.xml, an embedded/app-assembly Hadoop config that dropped defaults, or a suite whose config suffix has no hadoop.security.crypto.codec.classes.* entry.

Common situations: Applications constructing Configuration manually (new Configuration(false) plus partial resources); Oozie/Spark assemblies pruning default XMLs; disabling/renaming crypto codec properties for a security review and forgetting the encrypted-path use case.

Related errors

• No KeyProvider is configured, cannot access an encrypted fil
• Invalid cipher suite, %s=%s
• Could not instantiate KeyProvider for uri: ${providerUri}
• KeyProvider ${keyProvider} was found but it is a transient p
• "Can't create an encryption zone for " + src + " since no ke

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