grafana/k6 · error

the startVUs exceed max limit of %d

Error message

the startVUs exceed max limit of %d

What it means

Raised by validateTargetShifts (called from RampingVUsConfig.Validate) when startVUs exceeds maxConcurrentVUs, the hard internal cap on concurrently running VUs. This guards against configurations that could exhaust system resources.

Source

Thrown at lib/executor/ramping_vus.go:728

			case <-timer.C:
				// now we do a step
			}
		}
		return false
	}
}

// validateTargetShifts validates the VU Target shifts.
// It will append an error for any VU target that is larger than the maximum value allowed.
// Each Stage needs a Target value. The stages array can be empty. The Targes could be negative.
//
// TODO: after https://github.com/grafana/k6/issues/1499 this validation
// function could be useless.
func validateTargetShifts(startVUs int64, stages []Stage) []error {
	var errors []error

	if startVUs > int64(maxConcurrentVUs) {
		errors = append(errors, fmt.Errorf(
			"the startVUs exceed max limit of %d", maxConcurrentVUs))
	}

	for i := range stages {
		if stages[i].Target.Int64 > int64(maxConcurrentVUs) {
			errors = append(errors, fmt.Errorf(
				"target for stage %d exceeds max limit of %d", i+1, maxConcurrentVUs))
		}
	}

	return errors
}

View on GitHub (pinned to 01ffac6f24)

Solutions

1. Lower startVUs to at most the maxConcurrentVUs limit
2. Distribute load across multiple scenarios or k6 instances instead of one huge VU count

When it happens

Trigger: Thrown at lib/executor/ramping_vus.go:728 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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