apache/flink · error · IllegalStateException

Memory segment does not represent off-heap buffer

Error message

Memory segment does not represent off-heap buffer

What it means

MemorySegment.getOffHeapBuffer() returns the underlying ByteBuffer only for off-heap segments. For on-heap segments offHeapBuffer is null, so it throws IllegalStateException('Memory segment does not represent off-heap buffer'). It is the dual of getArray(), which only works for heap segments.

Source

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

    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");
        }
    }

    /**
     * Returns the memory address of off-heap memory segments.
     *
     * @return absolute memory address outside the heap
     * @throws IllegalStateException if the memory segment does not represent off-heap memory
     */
    public long getAddress() {
        if (heapMemory == null) {
            return address;
        } else {
            throw new IllegalStateException("Memory segment does not represent off heap memory");
        }
    }

    /**

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Branch on segment.isOffHeap() before choosing getOffHeapBuffer() vs getArray().
2. If you only need to read/write bytes positionally, use segment.get(index)/put(index, b) or the bulk get/put methods that work on either backing.
3. Use segment.wrap(offset, length) to obtain a ByteBuffer view valid for both heap and off-heap owned segments.

Example fix

// before
ByteBuffer buf = segment.getOffHeapBuffer(); // IllegalStateException on heap segment

// after
ByteBuffer buf = segment.isOffHeap()
        ? segment.getOffHeapBuffer()
        : segment.wrap(0, segment.size());

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

When it happens

Trigger: Calling getOffHeapBuffer() on a segment created by MemorySegmentFactory.wrap(byte[]) or allocateUnpooledSegment (heap-backed).

Common situations: Utility code assuming all segments are off-heap (e.g. written against a RocksDB/off-heap pipeline) executed against heap segments in tests or on a differently configured cluster; mixing segment factories across code paths.

Related errors

• Memory segment does not represent heap memory
• 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/67023c95cf2d43bb. Report an issue: GitHub.