the 'toLine' option must be greater than or equal to 0; got

Error message

the 'toLine' option must be greater than or equal to 0; got %d

What it means

validateOptions in the experimental CSV reader rejects a negative toLine (internal/js/modules/k6/experimental/csv/reader.go:153). toLine is the inclusive 0-based stop line; a negative value never selects a valid window and is rejected at construction time with the offending value in the message.

Source

Thrown at internal/js/modules/k6/experimental/csv/reader.go:153

		toLineSet        = options.ToLine.Valid
		skipFirstLineSet = options.SkipFirstLine
		asObjectsEnabled = options.AsObjects.Valid && options.AsObjects.Bool
	)

	if asObjectsEnabled && skipFirstLineSet {
		return fmt.Errorf("the 'header' option cannot be enabled when 'skipFirstLine' is true")
	}

	if asObjectsEnabled && fromLineSet && options.FromLine.Int64 > 0 {
		return fmt.Errorf("the 'header' option cannot be enabled when 'fromLine' is set to a value greater than 0")
	}

	if fromLineSet && options.FromLine.Int64 < 0 {
		return fmt.Errorf("the 'fromLine' option must be greater than or equal to 0; got %d", options.FromLine.Int64)
	}

	if toLineSet && options.ToLine.Int64 < 0 {
		return fmt.Errorf("the 'toLine' option must be greater than or equal to 0; got %d", options.ToLine.Int64)
	}

	if fromLineSet && toLineSet && options.FromLine.Int64 >= options.ToLine.Int64 {
		return fmt.Errorf(
			"the 'fromLine' option must be less than the 'toLine' option; got 'fromLine': %d, 'toLine': %d",
			options.FromLine.Int64, options.ToLine.Int64,
		)
	}

	return nil
}

View on GitHub (pinned to 93accf6570)

Solutions

Omit toLine entirely to read to the end of the file
Clamp computed bounds with Math.max(0, n)
Guard against empty selections before building parser options

Example fix

// before
const parser = new csv.Parser(file, { toLine: rowCount - 1 }); // rowCount = 0 -> -1

// after
const opts = { toLine: Math.max(0, rowCount - 1) };
const parser = new csv.Parser(file, rowCount > 0 ? opts : {});

Defensive patterns

Strategy: validation

Validate before calling

function clampToLine(o) {
  if (o.toLine !== undefined && o.toLine < 0) {
    throw new Error(`toLine must be >= 0, got ${o.toLine}`);
  }
  return o;
}
// or: if (o.toLine < 0) delete o.toLine; // read to EOF

Try / catch

try { new csv.Parser(file, opts); } catch (e) { if (/toLine.*greater than or equal/.test(e.message)) { delete opts.toLine; /* retry */ } throw e; }

Prevention

Guard count-based bounds against empty inputs (count = 0 makes count-1 negative)
Omit toLine instead of passing -1 to mean 'until the end'

When it happens

Trigger: `new csv.Parser(file, { toLine: -1 })` or `csv.parse(file, { toLine: -10 })` - typically a computed bound (e.g. count - 1 with count = 0) or a sentinel value passed through from config.

Common situations: Empty input files making count-based arithmetic go negative; copying inclusive/exclusive logic from another language where -1 means 'until the end'.

Related errors

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/62ce36b3951e6286. Report an issue: GitHub.