apache/hadoop · error · IOException

Client does not support specified CryptoProtocolVersion {} v

Error message

Client does not support specified CryptoProtocolVersion {} version number{}

What it means

When reading a file in an HDFS encryption zone, the NameNode returns FileEncryptionInfo containing a CryptoProtocolVersion. HdfsKMSUtil.getCryptoProtocolVersion checks CryptoProtocolVersion.supports(version); if this client build does not recognize/support that protocol number, it throws before any key decryption happens. It is a client-vs-NameNode capability gap on the encryption protocol, not a key or permission problem.

Source

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

   */
  public static KeyProvider createKeyProvider(
      final Configuration conf) throws IOException {
    return KMSUtil.createKeyProvider(conf, keyProviderUriKeyName);
  }

  /**
   * Obtain the crypto protocol version from the provided FileEncryptionInfo,
   * checking to see if this version is supported by.
   *
   * @param feInfo FileEncryptionInfo
   * @return CryptoProtocolVersion from the feInfo
   * @throws IOException if the protocol version is unsupported.
   */
  public static CryptoProtocolVersion getCryptoProtocolVersion(
      FileEncryptionInfo feInfo) throws IOException {
    final CryptoProtocolVersion version = feInfo.getCryptoProtocolVersion();
    if (!CryptoProtocolVersion.supports(version)) {
      throw new IOException("Client does not support specified " +
          "CryptoProtocolVersion " + version.getDescription() + " version " +
          "number" + version.getVersion());
    }
    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 {

View on GitHub (pinned to 2add963021)

Solutions

1. Upgrade the client's Hadoop jars to at least the cluster's version so the CryptoProtocolVersion is supported
2. Deduplicate hadoop-common on the client classpath so a stale enum set is not used
3. If stuck on an old client, read the data through a gateway (HTTPFS/WebHDFS with a modern backend, or copy via an up-to-date tool)

Example fix

# before
export HADOOP_CLASSPATH=/opt/old-hadoop-2.7/*   # client predates protocol version

# after
export HADOOP_CLASSPATH=/opt/hadoop-3.3.6/*      # match or exceed cluster version

// Gate encrypted-path access on client capability:
CryptoProtocolVersion[] supported = CryptoProtocolVersion.supported();
// After getFileEncryptionInfo (or on FileNotFoundException-free open), compare
// feInfo.getCryptoProtocolVersion() against supported before opening streams.

private static boolean clientSupportsProtocol(FileEncryptionInfo feInfo) {
  return CryptoProtocolVersion.supports(feInfo.getCryptoProtocolVersion());
}

try {
  in = fs.open(path);
} catch (IOException e) {
  if (e.getMessage().contains("does not support specified CryptoProtocolVersion")) {
    throw new UnsupportedOperationException("Upgrade client Hadoop jars to read this encryption zone", e);
  }
  throw e;
}

When it happens

Trigger: Opening/reading a file inside an encryption zone with a client whose Hadoop version predates the protocol version the NameNode stamped on the file (e.g., UNKNOWN or a later enum value); downgraded client jars against a newer cluster; classpath mixing old hadoop-common with new hadoop-hdfs-client.

Common situations: Old CLI/Hive/Spark distributions reading encryption-zone data on an upgraded cluster; partial client upgrades where hdfs-common comes from an older artifact; accessing files encrypted by a future Hadoop release.

Related errors

• NameNode specified unknown CipherSuite with ID {}, cannot in
• No configuration found for the cipher suite {} prefixed with
• No KeyProvider is configured, cannot access an encrypted fil
• Could not instantiate KeyProvider for uri: ${providerUri}
• KeyProvider ${keyProvider} was found but it is a transient p

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