grafana/k6 · error

the 'header' option cannot be enabled when 'fromLine' is set

Error message

the 'header' option cannot be enabled when 'fromLine' is set to a value greater than 0

What it means

Thrown by k6's experimental CSV module (k6/experimental/csv) when a Parser is constructed or csv.parse() is called with the asObjects option enabled (the message calls it 'header') together with fromLine set to a value greater than 0. When asObjects is on, NewReaderFrom unconditionally consumes the first physical line as the column-name header, so a fromLine that skips past line 0 would make header semantics ambiguous; validateOptions() rejects the combination up front (internal/js/modules/k6/experimental/csv/reader.go:144). Via the JS APIs the error is wrapped as 'failed to create a new parser; reason: ...' before any row is read.

Source

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

	return record, nil
}

// 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

  1. Drop the fromLine option (or set it to 0): with asObjects: true the header line is consumed automatically and data rows start right after it
  2. If you must skip leading lines, remove asObjects: true and consume rows as arrays, skipping rows in plain JS
  3. Restructure the CSV so the header is the first physical line and the rows you want follow it

Example fix

// before
const parser = new csv.Parser(file, { asObjects: true, fromLine: 1 });

// after
const parser = new csv.Parser(file, { asObjects: true });
Defensive patterns

Strategy: validation

Validate before calling

function assertCsvOptions(o) {
  if (o.asObjects && o.fromLine !== undefined && o.fromLine > 0) {
    throw new Error(`asObjects needs the header on line 0; got fromLine=${o.fromLine}. Remove fromLine or preprocess the file.`);
  }
  return o;
}
const parser = new csv.Parser(file, assertCsvOptions({ asObjects: true, fromLine: 1 }));

Try / catch

try {
  const parser = new csv.Parser(file, opts);
} catch (e) {
  if (/header.*option.*fromLine/.test(e.message)) { /* drop fromLine and rebuild opts */ }
  throw e;
}

Prevention

When it happens

Trigger: Calling `new csv.Parser(file, { asObjects: true, fromLine: 1 })` or `csv.parse(file, { asObjects: true, fromLine: 3 })` - any call where asObjects is truthy and fromLine is present and > 0.

Common situations: Scripts ported from CSV libraries where fromLine is 1-based: developers set fromLine: 1 meaning 'start at the first data row'. Also attempts to skip a preamble/comment block at the top of a file while still getting rows as objects keyed by header names.

Related errors

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