grafana/k6 · error

TestRunID is required

Error message

TestRunID is required

What it means

Output.startVersionedOutput requires an established cloud test run id before it can start pushing. testRunID is populated from config.PushRefID or by creating a test run during output start; if it is empty at this point the invariant fails with 'TestRunID is required'. In the standard flow this should not be reachable — it indicates the run-creation step was skipped, failed earlier, or the output was constructed/assembled programmatically without a run.

Source

Thrown at internal/output/cloud/output.go:471

			// result_status variable, which signifies whether the thresholds
			// passed or failed (failure also called "tainted" in some places of
			// the API here). The run_status signifies whether the test run
			// finished normally and has a few fixed failures values.
			//
			// So, this specific k6 error will be communicated to the cloud only
			// via result_status, while the run_status will appear normal.
			return cloudapi.RunStatusFinished
		}
	}

	// By default, the catch-all error is "aborted by system", but let's log that
	out.logger.WithError(testErr).Debug("unknown test error classified as 'aborted by system'")
	return cloudapi.RunStatusAbortedSystem
}

func (out *Output) startVersionedOutput() error {
	if out.testRunID == "" {
		return errors.New("TestRunID is required")
	}
	var err error

	usageErr := out.usage.Strings("cloud/test_run_id", out.testRunID)
	if usageErr != nil {
		out.logger.Warning("Couldn't report test run id to usage as part of writing to k6 cloud")
	}

	// TODO: move here the creation of a new cloudapi.Client
	// so in the case the config has been overwritten the client uses the correct
	// value.
	//
	// This logic is handled individually by each single output, it has the downside
	// that we could break the logic and not catch easly it.

	switch out.config.APIVersion.Int64 {
	case int64(apiVersion1):
		err = errors.New("v1 is not supported anymore")

View on GitHub (pinned to 01ffac6f24)

Solutions

1. If pushing to a pre-provisioned run, set the run reference (K6_CLOUD_PUSH_REF_ID / config push ref id) so testRunID is non-empty
2. Check earlier log lines — a failed test-run creation (auth, network, token scope) usually precedes this error; fix that first
3. Verify you are not mixing provisioning modes (PushRefID + scoped credentials vs. normal cloud token)
4. If this reproduces with a plain k6 run -o cloud script.js, report it as a k6 bug with the config and logs

// Go — programmatic use: ensure a run reference before Start
if cfg.PushRefID.Valid && cfg.PushRefID.String != "" {
    // direct-push mode carries its own testRunID
} else if tokenNotConfigured(cfg) {
    return errors.New("cloud output needs a token (K6_CLOUD_TOKEN) to create a test run")
}

When it happens

Trigger: Programmatic use of the cloud output that calls Start without going through the provisioning/create-run path and without PushRefID; an earlier failure in the start sequence that left testRunID unset; a hand-built Config that sets push-mode flags but no ref id.

Common situations: Embedding k6 as a library and wiring outputs manually; forks/wrappers that reorder output initialization; upgrading across k6 versions where the start sequence changed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• script name not set, please specify K6_CLOUD_NAME or options
• tests with unspecified duration are not allowed when outputt
• both K6_CLOUD_METRICS_PUSH_URL and K6_CLOUD_TEST_RUN_TOKEN m
• v1 is not supported anymore
• access token not configured

AI-assisted analysis of grafana/k6@01ffac6f24 (2026-08-18). Data as JSON: /api/errors/59b01794b71241a3. Report an issue: GitHub.