grafana/k6 · error

initializing feature flags: %w

Error message

initializing feature flags: %w

What it means

Emitted by resolveFeatureFlags when features.Init fails to reconcile the three feature-flag surfaces: CLI --features, the JSON config `features` key, and environment variables (K6_* runtime env). Init resolves each supplied name against the registered feature-flag definitions (and their aliases) and errors on unknown flag names or values that cannot be applied to the flag fields.

Source

Thrown at internal/cmd/features.go:119

	fileConf, err := readDiskConfig(gs)
	if err != nil {
		return errext.WithExitCodeIfNone(
			fmt.Errorf("failed to load the configuration file from the local file system: %w", err),
			exitcodes.InvalidConfig,
		)
	}
	jsonSurface := features.Source{Values: fileConf.Features, Supplied: fileConf.Features != nil}

	envSurface := maps.Clone(gs.Env)
	if envSurface == nil {
		envSurface = make(map[string]string)
	}
	maps.Copy(envSurface, piState.RuntimeOptions.Env)

	flags, err := features.Init(gs.Logger, cli, jsonSurface, envSurface)
	if err != nil {
		return fmt.Errorf("initializing feature flags: %w", err)
	}
	piState.FeatureFlags = flags

	for _, name := range flags.Activated() {
		if err := gs.Usage.Strings("features", name); err != nil {
			gs.Logger.WithError(err).Debugf("reporting feature usage for %q", name)
		}
	}

	propagateFeatureEnv(piState.RuntimeOptions.Env, flags.Activated())
	return nil
}

func warnOnScriptOptionsFeatures(logger logrus.FieldLogger, opts lib.Options) {
	if len(opts.Features) == 0 {
		return
	}
	logger.WithField("source", "options").

View on GitHub (pinned to 93accf6570)

Solutions

1. Run `k6 features` to list every valid flag name and lifecycle for your exact binary
2. Correct the offending surface: fix the name in --features, the config file `features` array, or the env var
3. Remove flags that no longer exist in your k6 version instead of keeping them 'just in case'
4. Pin/align the k6 version in CI so documented flag names match the binary in use

Example fix

# before
$ k6 run --features expermental-native-histograms script.js
# error: initializing feature flags: ...

# after
$ k6 features   # confirm the exact name
$ k6 run --features experimental-native-histograms script.js

# Only pass flags your binary actually knows
for f in $(k6 features -o json | jq -r '.[].name'); do echo "ok:$f"; done
# then diff your --features / K6_FEATURES values against that list before running

When it happens

Trigger: Passing a misspelled or unregistered flag: `k6 run --features expermental-native-histograms script.js`; a `features: ["nope"]` array in the config file; K6_FEATURES-style env vars with names that match no declared flag/alias; values that are not valid booleans for a flag.

Common situations: Feature flags renamed/removed between k6 versions (scripts or CI env carrying old experimental names); typos in pipelines; copying flag lists from docs for a different k6 version. The registered flags in this build are visible via `k6 features`.

Related errors

• 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
• requestsBurst must be greater than 0

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