{"record":{"id":"3bbb999bdae01cfe","repo":"apache/hadoop","slug":"client-does-not-support-specified-cryptoprotocolve","errorCode":null,"errorMessage":"Client does not support specified CryptoProtocolVersion {} version number{}","messagePattern":"Client does not support specified CryptoProtocolVersion (.+?) version number(.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/HdfsKMSUtil.java","lineNumber":86,"sourceCode":"   */\n  public static KeyProvider createKeyProvider(\n      final Configuration conf) throws IOException {\n    return KMSUtil.createKeyProvider(conf, keyProviderUriKeyName);\n  }\n\n  /**\n   * Obtain the crypto protocol version from the provided FileEncryptionInfo,\n   * checking to see if this version is supported by.\n   *\n   * @param feInfo FileEncryptionInfo\n   * @return CryptoProtocolVersion from the feInfo\n   * @throws IOException if the protocol version is unsupported.\n   */\n  public static CryptoProtocolVersion getCryptoProtocolVersion(\n      FileEncryptionInfo feInfo) throws IOException {\n    final CryptoProtocolVersion version = feInfo.getCryptoProtocolVersion();\n    if (!CryptoProtocolVersion.supports(version)) {\n      throw new IOException(\"Client does not support specified \" +\n          \"CryptoProtocolVersion \" + version.getDescription() + \" version \" +\n          \"number\" + version.getVersion());\n    }\n    return version;\n  }\n\n  /**\n   * Obtain a CryptoCodec based on the CipherSuite set in a FileEncryptionInfo\n   * and the available CryptoCodecs configured in the Configuration.\n   *\n   * @param conf   Configuration\n   * @param feInfo FileEncryptionInfo\n   * @return CryptoCodec\n   * @throws IOException if no suitable CryptoCodec for the CipherSuite is\n   *                     available.\n   */\n  public static CryptoCodec getCryptoCodec(Configuration conf,\n      FileEncryptionInfo feInfo) throws IOException {","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/HdfsKMSUtil.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the client's Hadoop jars to at least the cluster's version so the CryptoProtocolVersion is supported","Deduplicate hadoop-common on the client classpath so a stale enum set is not used","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)"],"exampleFix":"# before\nexport HADOOP_CLASSPATH=/opt/old-hadoop-2.7/*   # client predates protocol version\n\n# after\nexport HADOOP_CLASSPATH=/opt/hadoop-3.3.6/*      # match or exceed cluster version","handlingStrategy":"validation","validationCode":"// Gate encrypted-path access on client capability:\nCryptoProtocolVersion[] supported = CryptoProtocolVersion.supported();\n// After getFileEncryptionInfo (or on FileNotFoundException-free open), compare\n// feInfo.getCryptoProtocolVersion() against supported before opening streams.","typeGuard":"private static boolean clientSupportsProtocol(FileEncryptionInfo feInfo) {\n  return CryptoProtocolVersion.supports(feInfo.getCryptoProtocolVersion());\n}","tryCatchPattern":"try {\n  in = fs.open(path);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"does not support specified CryptoProtocolVersion\")) {\n    throw new UnsupportedOperationException(\"Upgrade client Hadoop jars to read this encryption zone\", e);\n  }\n  throw e;\n}","preventionTips":["Keep client Hadoop versions at or above the cluster version when reading encryption zones","Include an encryption-zone read in smoke tests after any cluster upgrade","Deduplicate hadoop-common jars so an old CryptoProtocolVersion enum never wins"],"tags":["hdfs","encryption","hdfs-encryption-zones","version-mismatch","kms"],"backgroundTag":"client-server-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}