grafana/k6 · error

setupTimeout must be positive

Error message

setupTimeout must be positive

What it means

Emitted by Options.Validate (lib/options.go:547-549) when setupTimeout is explicitly specified but not strictly positive (<= 0). setupTimeout bounds how long the exported setup() function may run before the test is aborted. Only a specified (Valid) value is checked — omitting the option keeps the default (60s). Zero or negative timeouts are rejected because they would abort setup before it can execute.

Source

Thrown at lib/options.go:548

	// TODO: validate all of the other options... that we should have already been validating...
	// TODO: maybe integrate an external validation lib: https://github.com/avelino/awesome-go#validation
	var validationErrors []error
	if o.ExecutionSegmentSequence != nil {
		var segmentFound bool
		if slices.ContainsFunc(*o.ExecutionSegmentSequence, o.ExecutionSegment.Equal) {
			segmentFound = true
		}
		if !segmentFound {
			validationErrors = append(validationErrors,
				fmt.Errorf("provided segment %s can't be found in sequence %s",
					o.ExecutionSegment, o.ExecutionSegmentSequence))
		}
	}
	validationErrors = append(validationErrors, o.Scenarios.Validate()...)

	// Duration
	if o.SetupTimeout.Valid && o.SetupTimeout.Duration <= 0 {
		validationErrors = append(validationErrors, errors.New("setupTimeout must be positive"))
	}
	return validationErrors
}

// ForEachSpecified enumerates all struct fields and calls the supplied function with each
// element that is valid. It panics for any unfamiliar or unexpected fields, so make sure
// new fields in Options are accounted for.
func (o Options) ForEachSpecified(structTag string, callback func(key string, value any)) {
	structType := reflect.TypeFor[Options]()
	structVal := reflect.ValueOf(o)
	for i := 0; i < structType.NumField(); i++ {
		fieldType := structType.Field(i)
		fieldVal := structVal.Field(i)
		value := fieldVal.Interface()

		var shouldCall bool
		switch fieldType.Type.Kind() {
		case reflect.Struct:

View on GitHub (pinned to 93accf6570)

Solutions

1. Remove the setupTimeout option to use the default of 60s
2. Or set a positive duration large enough for setup work, e.g. setupTimeout: '5m'; to effectively disable it use a very large value such as '1h'

Example fix

// before
export const options = { setupTimeout: '0s' };

// after
export const options = { setupTimeout: '5m' };

// JS: reject non-positive timeouts in generated options
function timeout(v, fallback) {
  if (!v) return fallback;
  const m = /^([0-9]+(?:\.[0-9]+)?)(ms|s|m|h)$/.exec(v);
  if (!m || parseFloat(m[1]) <= 0) throw new Error(`invalid timeout: ${v}`);
  return v;
}
export const options = { setupTimeout: timeout(__ENV.SETUP_TIMEOUT, '60s') };

When it happens

Trigger: Exporting options = { setupTimeout: '0s' } or { setupTimeout: '-5s' }; also when CLI flag --setup-timeout 0s or env K6_SETUP_TIMEOUT=0s is set. Validation runs during option consolidation before the test starts.

Common situations: Users trying to disable the setup timeout by setting it to zero (not supported — use a large value like '1h' instead); CI pipelines templating timeout values that resolve empty/zero; sign typos in generated configs.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• scenario name can't be empty
• urlTemplate must contain {key} placeholder
• urlTemplate must be an absolute URL with a scheme (e.g., htt
• timeout must be greater than 0
• requestsPerMinuteLimit must be greater than 0

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