grafana/k6 · error

failed to unescape header key %q: %w

Error message

failed to unescape header key %q: %w

What it means

In parseHeaders of the OpenTelemetry output, header keys are URL-escaped so they can contain special characters; url.PathUnescape on the key failed (invalid percent-encoding, e.g. '%ZZ'). The configured header key cannot be decoded, so exporter setup is aborted.

Source

Thrown at internal/output/opentelemetry/exporter.go:119

	if tlsConfig != nil {
		opt = append(opt, otlpmetricgrpc.WithTLSCredentials(credentials.NewTLS(tlsConfig)))
	}

	return otlpmetricgrpc.New(ctx, opt...)
}

func parseHeaders(raw string) (map[string]string, error) {
	headers := make(map[string]string)
	for header := range strings.SplitSeq(raw, ",") {
		rawKey, rawValue, ok := strings.Cut(header, "=")
		if !ok {
			return nil, fmt.Errorf("invalid header %q, expected format key=value", header)
		}

		key, err := url.PathUnescape(rawKey)
		if err != nil {
			return nil, fmt.Errorf("failed to unescape header key %q: %w", rawKey, err)
		}

		value, err := url.PathUnescape(rawValue)
		if err != nil {
			return nil, fmt.Errorf("failed to unescape header value %q: %w", rawValue, err)
		}

		headers[key] = value
	}

	return headers, nil
}

View on GitHub (pinned to 01ffac6f24)

Solutions

1. Fix or remove the invalid percent-encoding in the header key
2. Encode special characters properly, e.g. space as %20

When it happens

Trigger: Thrown at internal/output/opentelemetry/exporter.go:119 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grafana/k6@01ffac6f24 (2026-08-18). Data as JSON: /api/errors/b0863e117160b527. Report an issue: GitHub.