{"record":{"id":"b371bf31bfc377ac","repo":"apache/flink","slug":"wrap-is-not-supported-by-this-segment-this-usuall","errorCode":null,"errorMessage":"Wrap is not supported by this segment. This usually indicates that the underlying memory is unsafe, thus transferring of ownership is not allowed.","messagePattern":"Wrap is not supported by this segment\\. This usually indicates that the underlying memory is unsafe, thus transferring of ownership is not allowed\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/core/memory/MemorySegment.java","lineNumber":323,"sourceCode":"        } else {\n            throw new IllegalStateException(\"Memory segment does not represent off heap memory\");\n        }\n    }\n\n    /**\n     * Wraps the chunk of the underlying memory located between <tt>offset</tt> and <tt>offset +\n     * length</tt> in a NIO ByteBuffer. The ByteBuffer has the full segment as capacity and the\n     * offset and length parameters set the buffers position and limit.\n     *\n     * @param offset The offset in the memory segment.\n     * @param length The number of bytes to be wrapped as a buffer.\n     * @return A <tt>ByteBuffer</tt> backed by the specified portion of the memory segment.\n     * @throws IndexOutOfBoundsException Thrown, if offset is negative or larger than the memory\n     *     segment size, or if the offset plus the length is larger than the segment size.\n     */\n    public ByteBuffer wrap(int offset, int length) {\n        if (!allowWrap) {\n            throw new UnsupportedOperationException(\n                    \"Wrap is not supported by this segment. This usually indicates that the underlying memory is unsafe, thus transferring of ownership is not allowed.\");\n        }\n        return wrapInternal(offset, length);\n    }\n\n    private ByteBuffer wrapInternal(int offset, int length) {\n        if (address <= addressLimit) {\n            if (heapMemory != null) {\n                return ByteBuffer.wrap(heapMemory, offset, length);\n            } else {\n                try {\n                    ByteBuffer wrapper = Preconditions.checkNotNull(offHeapBuffer).duplicate();\n                    wrapper.limit(offset + length);\n                    wrapper.position(offset);\n                    return wrapper;\n                } catch (IllegalArgumentException e) {\n                    throw new IndexOutOfBoundsException();\n                }","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/core/memory/MemorySegment.java#L305-L341","documentation":"MemorySegment.wrap(offset, length) exposes the segment's memory as a NIO ByteBuffer that aliases the same memory. For segments created with allowWrap == false (unsafe memory whose ownership must not be transferred, e.g. wrapped foreign/off-heap memory) it throws UnsupportedOperationException, because handing out an aliasing ByteBuffer would let external code read/write memory Flink does not own.","triggerScenarios":"Calling wrap() on a segment produced by MemorySegmentFactory.wrapOffHeapMemory(ByteBuffer) or other factories that create segments with allowWrap=false; typically to feed the memory to an API that takes a ByteBuffer.","commonSituations":"Operators trying to hand Flink-managed off-heap memory to third-party libraries (compression codecs, network zero-copy sends) that require ByteBuffers; code that works with owned heap/off-heap segments but fails once memory comes from a foreign owner.","solutions":["Copy the bytes into a buffer you own instead of wrapping: byte[] out = new byte[len]; segment.get(offset, out, 0, len); ByteBuffer.wrap(out).","Use wrap() only on segments allocated directly (heap array or allocateOffHeapMemory), where ownership transfer is safe.","If zero-copy is required, restructure so the foreign memory owner creates the ByteBuffer and Flink wraps it, not the reverse."],"exampleFix":"// before\nByteBuffer view = segment.wrap(offset, length); // UnsupportedOperationException on non-ownable memory\n\n// after\nbyte[] copy = new byte[length];\nsegment.get(offset, copy, 0, length);\nByteBuffer view = ByteBuffer.wrap(copy);","handlingStrategy":"fallback","validationCode":"// no public getter for allowWrap; if ownership is uncertain, copy instead of wrap\nbyte[] copy = new byte[length];\nsegment.get(offset, copy, 0, length);\nByteBuffer view = ByteBuffer.wrap(copy);","typeGuard":null,"tryCatchPattern":"try {\n    ByteBuffer view = segment.wrap(offset, length);\n} catch (UnsupportedOperationException e) {\n    // memory is not ownable: fall back to copying bytes out\n}","preventionTips":["Wrap only segments you allocated (heap array or allocateOffHeapMemory).","Never cache ByteBuffers derived from foreign-owned memory.","When integrating libraries needing ByteBuffers, budget a copy — zero-copy is not guaranteed by the segment API."],"tags":["memory","bytebuffer","flink-core","ownership"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}