apache/druid · error · IllegalStateException

Frame allocator is not available. The output channel might b

Error message

Frame allocator is not available. The output channel might be marked as read-only, hence memory allocator is not required.

What it means

PartitionedOutputChannel.getFrameMemoryAllocator() returns the MemoryAllocator used by producers to allocate frames for writing. For read-only channels no allocator is stored (null), so calling this getter throws ISE: a read-only consumer never needs an allocator, so requesting one indicates the caller is mistakenly treating a read-only channel as writable.

Source

Thrown at processing/src/main/java/org/apache/druid/frame/processor/PartitionedOutputChannel.java:105

   */
  public synchronized WritableFrameChannel getWritableChannel()
  {
    if (writableChannel == null) {
      throw new ISE("Writable channel is not available. The output channel might be marked as read-only,"
                    + " hence no writes are allowed.");
    } else {
      return writableChannel;
    }
  }

  /**
   * Returns the memory allocator for the writable channel. The producer uses this to generate frames for the channel.
   * Throws ISE if the output channel is read only.
   */
  public synchronized MemoryAllocator getFrameMemoryAllocator()
  {
    if (frameMemoryAllocator == null) {
      throw new ISE("Frame allocator is not available. The output channel might be marked as read-only,"
                    + " hence memory allocator is not required.");
    } else {
      return frameMemoryAllocator;
    }
  }

  /**
   * Returns the partitioned readable channel supplier of this pair. The consumer reads from this channel.
   */
  public synchronized Supplier<PartitionedReadableFrameChannel> getReadableChannelSupplier()
  {
    return readableChannelSupplier;
  }

  public synchronized PartitionedOutputChannel mapWritableChannel(final Function<WritableFrameChannel, WritableFrameChannel> mapFn)
  {
    if (writableChannel == null) {
      return this;

View on GitHub (pinned to 9b90983fd2)

Solutions

Construct the channel with readOnly=false when producers need to allocate and write frames.
Only request the allocator on the producer/writable side; pass null or skip allocation for read-only consumers.
Guard with a readOnly check before fetching the allocator and use an alternate code path for read-only channels.

Example fix

// before
MemoryAllocator allocator = outputChannel.getFrameMemoryAllocator();
// after
MemoryAllocator allocator = outputChannel.isReadOnly() ? null : outputChannel.getFrameMemoryAllocator();

Defensive patterns

Strategy: try-catch

Validate before calling

if (outputChannel.isReadOnly()) {
  // no allocator needed on the read-only path
  return;
}

Type guard

boolean needsAllocator(PartitionedOutputChannel ch) { return !ch.isReadOnly(); }

Try / catch

try {
  MemoryAllocator a = outputChannel.getFrameMemoryAllocator();
} catch (IllegalStateException e) {
  // use a null allocator path for read-only consumers
}

Prevention

Only request allocators on the writable/producer side.
Create channels readOnly=false when frames will be written.
Pass allocator availability through explicit parameters instead of pulling from possibly-read-only channels.

When it happens

Trigger: Calling getFrameMemoryAllocator() on a PartitionedOutputChannel created with readOnly=true, e.g. in runMerger wiring or openPartitionedChannel when the channel was constructed read-only.

Common situations: Stage code that unconditionally requests an allocator for every output; tests that build read-only channels then exercise producer paths; refactors flipping readOnly without auditing allocator usage.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/b9a1d00c09d6788f. Report an issue: GitHub.