apache/hadoop · error · IOException

NameNode specified unknown CipherSuite with ID {}, cannot in

Error message

NameNode specified unknown CipherSuite with ID {}, cannot instantiate CryptoCodec.

What it means

The FileEncryptionInfo for a file in an encryption zone carries a CipherSuite; when the client's CipherSuite enum cannot map the ID the NameNode sent, the suite equals CipherSuite.UNKNOWN and HdfsKMSUtil refuses to build a CryptoCodec, reporting the raw unknown ID. Like the protocol-version error, this is a client-too-old / jar-mismatch signal: the NameNode knows a cipher suite this client has never heard of.

Source

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

    }
    return version;
  }

  /**
   * 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.

View on GitHub (pinned to 2add963021)

Solutions

Upgrade the client hadoop-common/hdfs-client jars so the CipherSuite enum includes the NameNode's suite
Inspect the classpath for a stale hadoop-common jar and remove it (CipherSuite lives in hadoop-common)
Verify with the cluster admin which cipher suite the encryption zone uses (default AES/CTR/NoPadding) and that nothing exotic was enabled

Defensive patterns

Strategy: validation

Validate before calling

FileEncryptionInfo feInfo = getFileEncryptionInfo(fs, path);
if (feInfo != null && feInfo.getCipherSuite().equals(CipherSuite.UNKNOWN)) {
  throw new UnsupportedOperationException(
      "Client cannot recognize cipher suite ID " + feInfo.getCipherSuite().getUnknownValue()
      + " — upgrade client Hadoop jars");
}

Type guard

private static boolean cipherSuiteKnown(FileEncryptionInfo feInfo) {
  return feInfo != null && !feInfo.getCipherSuite().equals(CipherSuite.UNKNOWN);
}

Try / catch

try {
  return HdfsKMSUtil.decryptEncryptedDataEncryptionKey(feInfo, keyProvider);
} catch (IOException e) {
  if (e.getMessage().contains("unknown CipherSuite")) {
    // surface as a version-mismatch error with actionable text
    throw new UnsupportedOperationException("Client too old for cluster cipher suite", e);
  }
  throw e;
}

Prevention

Match client and cluster Hadoop versions in encrypted environments
Check CipherSuite.UNKNOWN early when you already hold the FileEncryptionInfo
Track vendor/fork extensions to cipher suites before rolling them out to mixed clients

When it happens

Trigger: Reading an encrypted file whose suite ID (from feInfo.getCipherSuite()) is not in the client's CipherSuite enum: newer NameNode with an extended suite list, fork-added suites, or an old hadoop-common shadowing a new one; also possible if a non-HDFS-compatible middle layer mangles the encryption info.

Common situations: Legacy Hive/Spark clients on upgraded encrypted clusters; mixed hadoop-common versions in application containers; vendor distributions with extra cipher suites.

Related errors

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