grafana/k6 · error

format of header must be header.k=v, received %q

Error message

format of header must be header.k=v, received %q

What it means

A key containing the substring 'header.' does not split on '.' into exactly two parts (file_persister.go:68). Header entries must have the exact form header.<name>=<value>, so extra dots in the key are rejected.

Source

Thrown at internal/js/modules/k6/browser/browser/file_persister.go:68

		kv := strings.Split(s, "=")
		if len(kv) != 2 {
			return presignedURLConfig{}, fmt.Errorf("format of value must be k=v, received %q", s)
		}

		k := kv[0]
		v := kv[1]

		// A key with "header." means that the header name is encoded in the
		// key, separated by a ".". Split the header on "." to retrieve the
		// header name. The header value should be present in v from the previous
		// split.
		var hv, hk string
		if strings.Contains(k, "header.") {
			hv = v

			hh := strings.Split(k, ".")
			if len(hh) != 2 {
				return presignedURLConfig{}, fmt.Errorf("format of header must be header.k=v, received %q", s)
			}

			k = hh[0]
			hk = hh[1]

			if hk == "" {
				return presignedURLConfig{}, fmt.Errorf("empty header key, received %q", s)
			}
		}

		switch k {
		case "url":
			u, err := url.ParseRequestURI(v)
			if err != nil && u.Scheme != "" && u.Host != "" {
				return presignedURLConfig{}, fmt.Errorf("invalid url %q", s)
			}
			presignedURL.getterURL = v
		case "basePath":

View on GitHub (pinned to 93accf6570)

Solutions

1. Use exactly one dot: header.Name=value; for header names containing dots, replace the dot with an underscore or the header name the server actually expects
2. Check for stray dots in the key portion of every header.* segment
3. Test the value with: echo "$V" | tr ',' '\n' | grep 'header\.' | awk -F. 'NF!=2{print "bad header: "$0; exit 1}'

Example fix

# before
K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://h/,header.Accept-Encoding=gzip"
# after
K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://h/,header.AcceptEncoding=gzip"

const bad = v.split(',').filter(s => s.includes('header.') && s.split('=')[0].split('.').length !== 2);
if (bad.length) throw new Error(`malformed header segments: ${bad.join(', ')}`);

When it happens

Trigger: K6_BROWSER_SCREENSHOTS_OUTPUT contains 'header.Accept-Encoding=gzip' (dot inside the header name), 'x.header.a=1', or 'header.1.2=v' - the key contains 'header.' and splits into 3 parts instead of 2.

Common situations: Copying multi-part header names (Accept-Encoding, Content-Disposition) verbatim into the env var; assuming a numbered header list syntax like 'header.1.1='; key typos introduced by shell word-splitting.

Related errors

• empty header key, received %q
• format of value must be k=v, received %q
• invalid option %q
• parsing %s: %w
• invalid url %q

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