The REST API server is disabled, but this command needs to r

Error message

The REST API server is disabled, but this command needs to read metrics from it. Enable it by setting --address or K6_ADDRESS.

What it means

The hidden `k6 stats` command shows live test metrics by querying the k6 REST API of a running test. If gs.Flags.Address is empty no API server was configured, so it aborts before creating the client instead of failing on connection.

Source

Thrown at internal/cmd/stats.go:24

	"github.com/spf13/cobra"

	"go.k6.io/k6/v2/api/v1/client"
	"go.k6.io/k6/v2/cmd/state"
)

func getCmdStats(gs *state.GlobalState) *cobra.Command {
	// statsCmd represents the stats command
	statsCmd := &cobra.Command{
		Use:    "stats",
		Short:  "Show test metrics",
		Hidden: true,
		Long: `Show test metrics.

  Use the global --address flag or the K6_ADDRESS environment variable to specify
  the URL to the API server.`,
		RunE: func(_ *cobra.Command, _ []string) error {
			if gs.Flags.Address == "" {
				return errors.New("The REST API server is disabled, but this command needs" + //nolint:staticcheck
					" to read metrics from it. Enable it by setting --address or K6_ADDRESS.")
			}
			c, err := client.New(gs.Flags.Address)
			if err != nil {
				return err
			}
			metrics, err := c.Metrics(gs.Ctx)
			if err != nil {
				return err
			}

			return yamlPrint(gs.Stdout, metrics)
		},
	}
	return statsCmd
}

View on GitHub (pinned to 93accf6570)

Solutions

Start the monitored run with the API enabled: `k6 run --address localhost:6565 script.js`
Then query it: `k6 stats --address localhost:6565` (K6_ADDRESS works too)
If the run is over, use the end-of-test summary or an output file instead of this live command

Example fix

# before
k6 stats

# after (terminal 1, then terminal 2)
k6 run --address localhost:6565 script.js
k6 stats --address localhost:6565

Defensive patterns

Strategy: validation

Validate before calling

k6_stats_or_fail() {
  [ -n "${K6_ADDRESS:-}" ] || { echo 'Set --address / K6_ADDRESS (and start the run with it) first' >&2; return 1; }
  k6 stats "$@"
}

Prevention

Start long-running tests with a fixed `--address localhost:6565` so stats/status/metrics always work
Prefer the summary or `--out json` when the run is already finished — k6 stats is live-only
Remember stats is a hidden REST-API client, not a file reader

When it happens

Trigger: Running `k6 stats` with neither --address nor K6_ADDRESS set; also when the target test was itself started without `--address`, nothing listens to query.

Common situations: Assuming `k6 stats` reads a local results file rather than a live REST endpoint; forgetting the original run must be started with `--address localhost:6565` (or K6_ADDRESS).

Related errors

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