grafana/k6 · error

the gracefulStop timeout can't be negative

Error message

the gracefulStop timeout can't be negative

What it means

Emitted by BaseConfig.Validate (lib/executor/base_config.go:69-71) when a scenario's gracefulStop is negative. gracefulStop (types.NullDuration) is how long k6 waits for already-running iterations to finish at the end of a scenario before forcibly stopping them (default 30s, DefaultGracefulStopValue at line 20). A negative grace period is meaningless and rejected.

Source

Thrown at lib/executor/base_config.go:70

	// even assigned by us:
	if bc.Name == "" {
		result = append(result, errors.New("scenario name can't be empty"))
	}
	if !scenarioNameWhitelist.MatchString(bc.Name) {
		result = append(result, errors.New(scenarioNameErr))
	}
	if bc.Exec.Valid && bc.Exec.String == "" {
		result = append(result, errors.New("exec value cannot be empty"))
	}
	if bc.Type == "" {
		result = append(result, errors.New("missing or empty type field"))
	}
	// The actually reasonable checks:
	if bc.StartTime.Duration < 0 {
		result = append(result, errors.New("the startTime can't be negative"))
	}
	if bc.GracefulStop.Duration < 0 {
		result = append(result, errors.New("the gracefulStop timeout can't be negative"))
	}
	return result
}

// GetName returns the name of the scenario.
func (bc BaseConfig) GetName() string {
	return bc.Name
}

// GetType returns the executor's type as a string ID.
func (bc BaseConfig) GetType() string {
	return bc.Type
}

// GetStartTime returns the starting time, relative to the beginning of the
// actual test, that this executor is supposed to execute.
func (bc BaseConfig) GetStartTime() time.Duration {
	return bc.StartTime.TimeDuration()

View on GitHub (pinned to 93accf6570)

Solutions

1. Use gracefulStop: '0s' to disable the grace period entirely
2. Or use a positive value like '30s' (default) or '1m' for longer iteration wind-down

Example fix

// before
export const options = {
  scenarios: { s: { executor: 'constant-vus', gracefulStop: '-1s', vus: 1, duration: '10s' } },
};

// after
export const options = {
  scenarios: { s: { executor: 'constant-vus', gracefulStop: '0s', vus: 1, duration: '10s' } },
};

// If 'no graceful stop' is intended, normalize to '0s'
const gs = __ENV.GRACEFUL_STOP || '30s';
if (gs.startsWith('-')) throw new Error('gracefulStop must be >= 0; use 0s to disable');

When it happens

Trigger: Setting scenarios: { smoke: { executor: 'constant-vus', gracefulStop: '-1s', ... } } or any config where the gracefulStop duration string parses negative. Only fires when the field is set, since the default set by NewBaseConfig is valid but not Valid (null), and negative durations always have Duration < 0.

Common situations: Attempting to express 'no graceful stop' with a negative value; the correct expression is gracefulStop: '0s'. Sign typos in generated configs also hit this.

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
• the scenario name should contain only numbers, latin letters
• exec value cannot be empty
• missing or empty type field
• the startTime can't be negative

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