apache/druid · error · org.apache.druid.java.util.common.IAE

pos out of range [ , ]

Error message

pos %d out of range [%d, %d]

What it means

LegacyFileWriteOutBytes.readFully checks pos against [0, writeOutBytes] (bytes written so far) and throws IAE when out of range. It prevents reading outside the data actually persisted by this writer.

Solutions

1. Recompute offsets against the current writer size before reading; do not trust persisted offsets without validation.
2. Call flush()/writeTo first to ensure logical and on-disk state agree.
3. Validate segment files (checksum/size metadata) and rebuild if offsets exceed the file's logical size.
4. Align writer/reader versions so offset layouts match.

Example fix

// before
legacy.readFully(offsetFromIndex, buf);
// after
if (offsetFromIndex < 0 || offsetFromIndex > legacy.writeOutBytes) {
  throw new IllegalStateException("invalid offset " + offsetFromIndex);
}
legacy.readFully(offsetFromIndex, buf);

if (offset < 0 || offset > legacy.writeOutBytes) throw new IllegalArgumentException("offset out of range: " + offset);

try { legacy.readFully(pos, buf); } catch (IllegalArgumentException e) { throw new IOException("bad offset " + pos, e); }

When it happens

Trigger: readFully(pos, buffer) with negative pos or pos beyond the bytes written: stale offsets from an older build of the same segment, mismatched size assumptions, or overflow.

Common situations: Reading legacy segments with offsets produced by a different writer; resuming a task against partially rewritten files; concurrent appends changing writeOutBytes between planning and reading.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• pos out of range [ , ]
• pos out of range [ , ]
• Failed to write to file
• Index metadata doesn't exist for segment
• Invalid arguments for reading

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/writeout/LegacyFileWriteOutBytes.java:141

  @Override
  public void writeTo(WritableByteChannel channel) throws IOException
  {
    flush();
    ch.position(0);
    try {
      ByteStreams.copy(ch, channel);
    }
    finally {
      ch.position(ch.size());
    }
  }

  @Override
  public void readFully(long pos, ByteBuffer buffer) throws IOException
  {
    if (pos < 0 || pos > writeOutBytes) {
      throw new IAE("pos %d out of range [%d, %d]", pos, 0, writeOutBytes);
    }
    flush();
    ch.read(buffer, pos);
    if (buffer.remaining() > 0) {
      throw new BufferUnderflowException();
    }
  }

  @Override
  public InputStream asInputStream() throws IOException
  {
    flush();
    return new FileInputStream(file);
  }

  @Override
  public boolean isOpen()
  {

View on GitHub (pinned to 9b90983fd2)