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

FileWriteOutBytes.readFully validates pos against [0, writeOutBytes] (the current logical file size) before reading from the channel. An IAE is thrown for positions outside this range, guarding against reads past written data or before the start of the file.

Solutions

1. Validate/recompute the offset from the current writer (writeOutBytes) before calling readFully.
2. Flush pending writes (flushIfNeeded/writeTo) so logical size matches on-disk size, then re-read.
3. If the offset source is a persisted index, verify segment integrity (checksums) and rebuild the segment.
4. Check for version skew between the code writing offsets and the code reading them.

Example fix

// before
fileWriteOutBytes.readFully(storedOffset, buf); // storedOffset from old index
// after
long pos = Math.min(storedOffset, fileWriteOutBytes.writeOutBytes);
if (pos != storedOffset) {
  log.warn("clamping stale offset %d -> %d", storedOffset, pos);
}
fileWriteOutBytes.readFully(pos, buf);

if (pos < 0 || pos > fileWriteOutBytes.writeOutBytes) throw new IllegalArgumentException("invalid pos: " + pos);

try { w.readFully(pos, buf); } catch (IllegalArgumentException e) { throw new IOException("offset out of range: " + pos, e); }

When it happens

Trigger: readFully(pos, buffer) with pos < 0 or pos > current written size: stale offsets after file shrink/rewrite, offsets from a different segment version, or overflowed computed offsets.

Common situations: Reading a segment index built with an older writer version; offset table out of sync after partial flush; copy/paste using file length on disk vs logical size mismatch; concurrent modification of the file.

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 [ , ]
• Invalid arguments for reading
• 'skip' must be greater than zero

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/writeout/FileWriteOutBytes.java:156

  @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)