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.

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
• Cannot retrieve Left value on a Right
• Cannot retrieve Right value on a Left
• Could not write bytes. Buffer overflow.

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

Appendix: 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)