What causes "Invalid start or len parameter" in apache/hadoop?

Clamp inputs: skip the call when start < 0 or len <= 0

apache/hadoop · error · IllegalArgumentException

Invalid start or len parameter

Error message

Invalid start or len parameter

What it means

Pure argument validation in getFileBlockLocations(FileStatus,start,len): a negative start or a negative len throws IllegalArgumentException before any location lookup. The companion case, start beyond EOF, is not an error - it returns an empty BlockLocation[].

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java:890

   *   "host2:9866","host3:9866","host4:9866","host5:9866"})
   * BlockLocation(offset: 3 * BLOCK_SIZE, length: 123, hosts: {"host1:9866",
   *   "host4:9866", "host5:9866"})
   * </pre>
   *
   * @param file FilesStatus to get data from
   * @param start offset into the given file
   * @param len length for which to get locations for
   * @throws IOException IO failure
   * @return block location array.
   */
  public BlockLocation[] getFileBlockLocations(FileStatus file,
      long start, long len) throws IOException {
    if (file == null) {
      return null;
    }

    if (start < 0 || len < 0) {
      throw new IllegalArgumentException("Invalid start or len parameter");
    }

    if (file.getLen() <= start) {
      return new BlockLocation[0];

    }
    String[] name = {"localhost:9866"};
    String[] host = {"localhost"};
    return new BlockLocation[] {
      new BlockLocation(name, host, 0, file.getLen()) };
  }

  /**
   * Return an array containing hostnames, offset and size of
   * portions of the given file.  For a nonexistent
   * file or regions, {@code null} is returned.
   *
   * This call is most helpful with location-aware distributed

View on GitHub (pinned to 2add963021)

Solutions

Clamp inputs: skip the call when start < 0 or len <= 0
Treat len == 0 or start >= file length as 'no blocks' and short-circuit (matches API behavior)
Fix the upstream arithmetic that produced the negative value - the exception is a symptom, not the bug

Example fix

// before
BlockLocation[] locs = fs.getFileBlockLocations(status, start, end - start);

// after
long len = end - start;
BlockLocation[] locs = (start < 0 || len <= 0)
    ? new BlockLocation[0]
    : fs.getFileBlockLocations(status, start, len);

Defensive patterns

Strategy: validation

Validate before calling

long len = end - start;
if (start < 0 || len < 0) {
  throw new IllegalArgumentException("bad range: start=" + start + " len=" + len);
}
BlockLocation[] locs = fs.getFileBlockLocations(status, start, len);

Prevention

Validate computed ranges at the point where they are computed
Never pass -1 sentinels into range APIs
Short-circuit zero-length ranges instead of calling the API

When it happens

Trigger: Computing ranges as start/end and passing len = end - start when end < start; passing -1 as a sentinel; custom InputFormat split math receiving stale or truncated file lengths.

Common situations: Custom InputFormat/RecordReader range arithmetic; files concurrently truncated so status.getLen() is smaller than a previously computed start; off-by-one bugs in offset math.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/ee339b9420058182. Report an issue: GitHub.