the 'fromLine' option must be greater than or equal to 0; go

Error message

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

What it means

validateOptions in the experimental CSV reader rejects a negative fromLine (internal/js/modules/k6/experimental/csv/reader.go:148). fromLine is a 0-based line index marking where reading starts; any value below 0 is a programming or configuration error, not an empty range. The offending value is included in the message.

Source

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

// validateOptions validates the reader options and returns an error if any validation fails.
func validateOptions(options options) error {
	var (
		fromLineSet      = options.FromLine.Valid
		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

Pass 0 (or omit fromLine) to start at the first line
Clamp computed indices with Math.max(0, n) before passing them
Convert internal sentinels to 0 or undefined before constructing the parser

Example fix

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

// after
const from = Math.max(0, startLine - 1);
const parser = new csv.Parser(file, { fromLine: from });

Defensive patterns

Strategy: validation

Validate before calling

function clampFromLine(o) {
  if (o.fromLine !== undefined && o.fromLine < 0) {
    throw new Error(`fromLine must be >= 0, got ${o.fromLine}`);
  }
  return o;
}
// or silently normalize: o.fromLine = Math.max(0, o.fromLine ?? 0);

Try / catch

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

Prevention

Never pass computed indices unchecked; clamp with Math.max(0, n)
Reserve -1 sentinels for your own code and convert to 0/undefined at the boundary

When it happens

Trigger: `new csv.Parser(file, { fromLine: -1 })` or `csv.parse(file, { fromLine: -5 })` - most often a computed index such as `lineNo - 1` evaluating negative when lineNo is 0.

Common situations: Off-by-one arithmetic on 1-based line numbers from external config or CSV headers; using -1 as a sentinel meaning 'from the beginning'; formulas that underflow when a selection is empty.

Related errors

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