grafana/k6 · error

{msg}

Error message

{msg}

What it means

`k6.fail(msg)` (internal/js/modules/k6/k6.go:66) is a deliberate abort primitive: "a fancy way of saying throw 'something'". It returns `errors.New(msg)`, so sobek throws an exception whose message is exactly the string you passed. The iteration is marked as failed and, by default, the VU stops the iteration (configurable via throw/usage options).

Source

Thrown at internal/js/modules/k6/k6.go:68

	return &K6{vu: vu}
}

// Exports returns the exports of the k6 module.
func (mi *K6) Exports() modules.Exports {
	return modules.Exports{
		Named: map[string]any{
			"check":      mi.Check,
			"fail":       mi.Fail,
			"group":      mi.Group,
			"randomSeed": mi.RandomSeed,
			"sleep":      mi.Sleep,
		},
	}
}

// Fail is a fancy way of saying `throw "something"`.
func (*K6) Fail(msg string) (sobek.Value, error) {
	return sobek.Undefined(), errors.New(msg)
}

// Sleep waits the provided seconds before continuing the execution.
func (mi *K6) Sleep(secs float64) {
	ctx := mi.vu.Context()
	timer := time.NewTimer(time.Duration(secs * float64(time.Second)))
	select {
	case <-timer.C:
	case <-ctx.Done():
		timer.Stop()
	}
}

// RandomSeed sets the seed to the random generator used for this VU.
func (mi *K6) RandomSeed(seed int64) {
	randSource := rand.New(rand.NewSource(seed)).Float64 //nolint:gosec
	mi.vu.Runtime().SetRandSource(randSource)
}

View on GitHub (pinned to 93accf6570)

Solutions

1. If the failure is intentional, verify the condition that triggers it and fix the test/target
2. Wrap the call site in try/catch when the abort should be recoverable or only mark a check
3. Replace k6.fail with check() when you want to record a failure without aborting the iteration

Example fix

// before
if (res.status !== 200) { k6.fail(`unexpected status ${res.status}`); }

// after (record without aborting)
check(res, { 'status is 200': (r) => r.status === 200 });

// after (recoverable abort)
try { if (res.status !== 200) k6.fail(`status ${res.status}`); }
catch (e) { console.warn('iteration aborted:', e.message); }

try {
  if (shouldAbort()) k6.fail(abortReason);
} catch (e) {
  console.warn(`iteration aborted: ${e.message}`);
  // optionally record a custom metric instead of failing the iteration
}

When it happens

Trigger: Calling `k6.fail('threshold breached')` anywhere in VU code — directly, inside helpers, or inside check/group callbacks. It is frequently used with custom threshold logic or to abort a scenario conditionally.

Common situations: Intentional abort when an application precondition fails; guard clauses that misuse k6.fail for control flow; copied scripts where the message is dynamic and unexpectedly triggers.

Related errors

• group() requires a callback as a second argument
• group() does not support async functions as arguments, pleas
• no checks provided to `check`
• the built-in check() does not support async functions as arg
• metrics must be declared in the init context

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