apache/flink · error · IllegalStateException

Memory segment does not represent heap memory

Error message

Memory segment does not represent heap memory

What it means

MemorySegment.getArray() returns the backing byte[] only for on-heap segments (created from a heap array). Off-heap segments have heapMemory == null, so getArray() throws IllegalStateException('Memory segment does not represent heap memory'). Off-heap memory cannot be exposed as a Java array because it lives outside the heap.

Source

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

     *
     * @return <tt>true</tt>, if the memory segment is backed by off-heap memory, <tt>false</tt> if
     *     it is backed by heap memory.
     */
    public boolean isOffHeap() {
        return heapMemory == null;
    }

    /**
     * Returns the byte array of on-heap memory segments.
     *
     * @return underlying byte array
     * @throws IllegalStateException if the memory segment does not represent on-heap memory
     */
    public byte[] getArray() {
        if (heapMemory != null) {
            return heapMemory;
        } else {
            throw new IllegalStateException("Memory segment does not represent heap memory");
        }
    }

    /**
     * Returns the off-heap buffer of memory segments.
     *
     * @return underlying off-heap buffer
     * @throws IllegalStateException if the memory segment does not represent off-heap buffer
     */
    public ByteBuffer getOffHeapBuffer() {
        if (offHeapBuffer != null) {
            return offHeapBuffer;
        } else {
            throw new IllegalStateException("Memory segment does not represent off-heap buffer");
        }
    }

    /**

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Branch on segment.isOffHeap(): use getOffHeapBuffer() (a ByteBuffer view) for off-heap segments and getArray() only for heap segments.
2. If a contiguous copy is required regardless of backing, copy out the bytes with segment.get(offset, target, 0, len) or wrap via segment.wrap(0, size) instead of assuming an array.
3. If your component fundamentally requires heap arrays, allocate the segment with MemorySegmentFactory.allocateUnpooledSegment(size) or wrap an existing byte[].

Example fix

// before
byte[] bytes = segment.getArray(); // IllegalStateException on off-heap

// after
if (segment.isOffHeap()) {
    ByteBuffer bytes = segment.getOffHeapBuffer();
    // ... read via ByteBuffer API
} else {
    byte[] bytes = segment.getArray();
}

if (!segment.isOffHeap()) {
    byte[] bytes = segment.getArray();
} else {
    ByteBuffer bytes = segment.getOffHeapBuffer();
}

When it happens

Trigger: Calling getArray() on a segment produced by MemorySegmentFactory.allocateOffHeapMemory / wrapOffHeapBuffer, or on segments handed out by a MemoryManager configured for off-heap memory.

Common situations: Code written and tested against heap segments (task-manager memory configured as managed heap or on-heap state backend) then run with off-heap memory configured (taskmanager.memory.managed.size with off-heap consumers, off-heap buffers); serializers or output paths that try to hand the raw byte[] to java.io APIs.

Related errors

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

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