apache/flink · error · UnsupportedOperationException

Wrap is not supported by this segment. This usually indicate

Error message

Wrap is not supported by this segment. This usually indicates that the underlying memory is unsafe, thus transferring of ownership is not allowed.

What it means

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.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/memory/MemorySegment.java:323

        } else {
            throw new IllegalStateException("Memory segment does not represent off heap memory");
        }
    }

    /**
     * Wraps the chunk of the underlying memory located between <tt>offset</tt> and <tt>offset +
     * length</tt> in a NIO ByteBuffer. The ByteBuffer has the full segment as capacity and the
     * offset and length parameters set the buffers position and limit.
     *
     * @param offset The offset in the memory segment.
     * @param length The number of bytes to be wrapped as a buffer.
     * @return A <tt>ByteBuffer</tt> backed by the specified portion of the memory segment.
     * @throws IndexOutOfBoundsException Thrown, if offset is negative or larger than the memory
     *     segment size, or if the offset plus the length is larger than the segment size.
     */
    public ByteBuffer wrap(int offset, int length) {
        if (!allowWrap) {
            throw new UnsupportedOperationException(
                    "Wrap is not supported by this segment. This usually indicates that the underlying memory is unsafe, thus transferring of ownership is not allowed.");
        }
        return wrapInternal(offset, length);
    }

    private ByteBuffer wrapInternal(int offset, int length) {
        if (address <= addressLimit) {
            if (heapMemory != null) {
                return ByteBuffer.wrap(heapMemory, offset, length);
            } else {
                try {
                    ByteBuffer wrapper = Preconditions.checkNotNull(offHeapBuffer).duplicate();
                    wrapper.limit(offset + length);
                    wrapper.position(offset);
                    return wrapper;
                } catch (IllegalArgumentException e) {
                    throw new IndexOutOfBoundsException();
                }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. 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).
2. Use wrap() only on segments allocated directly (heap array or allocateOffHeapMemory), where ownership transfer is safe.
3. If zero-copy is required, restructure so the foreign memory owner creates the ByteBuffer and Flink wraps it, not the reverse.

Example fix

// before
ByteBuffer view = segment.wrap(offset, length); // UnsupportedOperationException on non-ownable memory

// after
byte[] copy = new byte[length];
segment.get(offset, copy, 0, length);
ByteBuffer view = ByteBuffer.wrap(copy);

// no public getter for allowWrap; if ownership is uncertain, copy instead of wrap
byte[] copy = new byte[length];
segment.get(offset, copy, 0, length);
ByteBuffer view = ByteBuffer.wrap(copy);

try {
    ByteBuffer view = segment.wrap(offset, length);
} catch (UnsupportedOperationException e) {
    // memory is not ownable: fall back to copying bytes out
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The given buffer is neither an array-backed heap ByteBuffer,
• Could not write {numBytes} bytes. Buffer overflow.
• MemorySegment can be freed only once!
• Memory segment does not represent heap memory
• Memory segment does not represent off-heap buffer

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/b371bf31bfc377ac. Report an issue: GitHub.