{"record":{"id":"b282623b318c0090","repo":"apache/hadoop","slug":"classname-does-not-support-enhanced-byte-buffer","errorCode":null,"errorMessage":"${className} does not support enhanced byte buffer access.","messagePattern":"(.+?) does not support enhanced byte buffer access\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/CryptoInputStream.java","lineNumber":722,"sourceCode":"    return result;\n  }\n\n  @Override\n  public ByteBuffer read(ByteBufferPool bufferPool, int maxLength,\n      EnumSet<ReadOption> opts) throws IOException,\n      UnsupportedOperationException {\n    checkStream();\n    if (outBuffer.remaining() > 0) {\n      if (!(in instanceof Seekable)) {\n        throw new UnsupportedOperationException(in.getClass().getCanonicalName()\n            + \" does not support seek.\");\n      }\n      // Have some decrypted data unread, need to reset.\n      ((Seekable) in).seek(getPos());\n      resetStreamOffset(getPos());\n    }\n    if (!(in instanceof HasEnhancedByteBufferAccess)) {\n      throw new UnsupportedOperationException(in.getClass().getCanonicalName()\n          + \" does not support enhanced byte buffer access.\");\n    }\n    final ByteBuffer buffer = ((HasEnhancedByteBufferAccess) in).\n        read(bufferPool, maxLength, opts);\n    if (buffer != null) {\n      final int n = buffer.remaining();\n      if (n > 0) {\n        streamOffset += buffer.remaining(); // Read n bytes\n        final int pos = buffer.position();\n        decrypt(buffer, n, pos);\n      }\n    }\n    return buffer;\n  }\n\n  @Override\n  public void releaseBuffer(ByteBuffer buffer) {\n    if (!(in instanceof HasEnhancedByteBufferAccess)) {","sourceCodeStart":704,"sourceCodeEnd":740,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/CryptoInputStream.java#L704-L740","documentation":"After its seek housekeeping, read(ByteBufferPool, maxLength, opts) requires the wrapped stream to implement HasEnhancedByteBufferAccess, the marker interface for pooled/zero-copy ByteBuffer reads. Any other wrapped stream type gets UnsupportedOperationException ('does not support enhanced byte buffer access') naming the class.","triggerScenarios":"Calling the ByteBufferPool read API on a CryptoInputStream whose inner stream does not implement HasEnhancedByteBufferAccess — non-HDFS filesystems, wrapped local streams, or older HDFS clients without zero-copy support.","commonSituations":"Applications relying on zero-copy (direct-buffer) reads — columnar engines, mappers using elastiscale read paths — on encrypted files or on filesystem clients without zero-copy streams.","solutions":["Use plain read(byte[]) for encrypted streams; zero-copy is generally unavailable through the crypto layer","Check the underlying filesystem's zero-copy support before enabling such code paths for encrypted data","Catch UnsupportedOperationException and fall back to buffered reads"],"exampleFix":"// before\nByteBuffer zeroCopy = fsIn.read(bufferPool, maxLen, opts); // UOE without HasEnhancedByteBufferAccess\n\n// after\ntry {\n  ByteBuffer zeroCopy = fsIn.read(bufferPool, maxLen, opts);\n} catch (UnsupportedOperationException e) {\n  byte[] buf = new byte[maxLen];\n  int n = fsIn.read(buf, 0, maxLen); // buffered fallback\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  ByteBuffer b = fsIn.read(bufferPool, maxLen, opts);\n} catch (UnsupportedOperationException e) {\n  byte[] buf = new byte[maxLen];\n  int n = fsIn.read(buf, 0, maxLen); // buffered fallback\n}","preventionTips":["Disable zero-copy read paths for files inside encryption zones","Add a capability probe (one guarded call at open time) and cache the result per stream","Keep a single fallback utility mapping zero-copy misses to plain byte[] reads"],"tags":["crypto","hdfs","stream","bytebuffer","zero-copy","hadoop"],"backgroundTag":"unsupported-stream-operation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}