grafana/k6 · error

failed to register GRPC module metrics: %w

Error message

failed to register GRPC module metrics: %w

What it means

k6 registers three Counter metrics for the gRPC module (grpc_streams, grpc_streams_msgs_sent, grpc_streams_msgs_received) on the test-wide metric registry every time a VU instantiates 'k6/grpc' (internal/js/modules/k6/grpc/metrics.go:17-27). registry.NewMetric fails when one of these names already exists with a different metric type, and NewModuleInstance converts that failure into this thrown error during the init stage, before any traffic runs.

Source

Thrown at internal/js/modules/k6/grpc/grpc.go:47

	}
)

var (
	_ modules.Module   = &RootModule{}
	_ modules.Instance = &ModuleInstance{}
)

// New returns a pointer to a new RootModule instance.
func New() *RootModule {
	return &RootModule{}
}

// NewModuleInstance implements the modules.Module interface to return
// a new instance for each VU.
func (r *RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
	metrics, err := registerMetrics(vu.InitEnv().Registry)
	if err != nil {
		common.Throw(vu.Runtime(), fmt.Errorf("failed to register GRPC module metrics: %w", err))
	}

	mi := &ModuleInstance{
		vu:      vu,
		exports: make(map[string]any),
		metrics: metrics,
	}

	mi.exports["Client"] = mi.NewClient
	mi.defineConstants()
	mi.exports["Stream"] = mi.stream

	return mi
}

// NewClient is the JS constructor for the grpc Client.
func (mi *ModuleInstance) NewClient(_ sobek.ConstructorCall) *sobek.Object {
	rt := mi.vu.Runtime()

View on GitHub (pinned to 93accf6570)

Solutions

1. Rename the colliding custom metric: grep the script and shared helpers for grpc_streams, grpc_streams_msgs_sent, grpc_streams_msgs_received and change any non-Counter metric using those names
2. If you need those exact names, keep the type Counter so registry.NewMetric reuses the existing metric instead of erroring
3. If no custom metric collides, reproduce with a minimal script that only does `import grpc from 'k6/grpc'` and report it as a k6 bug with your k6 version

Example fix

// before
import { Trend } from 'k6/metrics';
import grpc from 'k6/grpc';
const streams = new Trend('grpc_streams');

// after
import { Trend } from 'k6/metrics';
import grpc from 'k6/grpc';
const streams = new Trend('my_grpc_streams');

// Reserved by k6's gRPC module: only Counters may use these names
const GRPC_RESERVED = ['grpc_streams', 'grpc_streams_msgs_sent', 'grpc_streams_msgs_received'];
// Before shipping, grep every new Counter/Trend/Gauge/Rate name against this list;
// any same-name non-Counter metric aborts script init.

When it happens

Trigger: A script that imports 'k6/grpc' and also creates its own metric with a reserved name and a non-Counter type, e.g. new Trend('grpc_streams') or new Rate('grpc_streams_msgs_sent') from 'k6/metrics' (same-name Counters are reused, other types collide). Also possible in xk6/embedded builds where another extension registers a colliding name, or when the VU's InitEnv registry is not initialized (k6 internal defect).

Common situations: Teams that named their own gRPC summary metrics before k6 reserved these names; k6 upgrades that introduced stream metrics; multi-extension builds with duplicate registrations.

Related errors

• metric tags: %w
• Unexpected end of selector while parsing selector `${selecto
• k6/experimental/grpc has been graduated, please use k6/net/g
• load must be called in the init context
• missing init environment

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