grafana/k6 · error

empty header key, received %q

Error message

empty header key, received %q

What it means

A header entry in K6_BROWSER_SCREENSHOTS_OUTPUT has an empty header name: the key is 'header.' followed directly by '=' (file_persister.go:75). After splitting on '.', the name part is the empty string.

Source

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

		// 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":
			presignedURL.basePath = v
		case "header":
			presignedURL.headers[hk] = hv
		default:
			return presignedURLConfig{}, fmt.Errorf("invalid option %q", k)
		}
	}

View on GitHub (pinned to 93accf6570)

Solutions

1. Supply a real header name: header.Authorization=Bearer xyz
2. Check that any templated header-name variables are actually set in CI
3. Grep the env var for 'header.=' and fix or remove that segment

Example fix

# before
K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://h/,header.=secret"
# after
K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://h/,header.Authorization=secret"

const empty = v.split(',').filter(s => s.startsWith('header.='));
if (empty.length) throw new Error(`empty header name in: ${empty.join(', ')}`);

When it happens

Trigger: K6_BROWSER_SCREENSHOTS_OUTPUT contains a segment like 'header.=value' - the key contains 'header.', splits into ['header',''], and the empty second part triggers this error. Often caused by a template variable that was meant to interpolate the header name but expanded to nothing.

Common situations: CI templates using 'header.${HEADER_NAME}=x' with an unset variable; hand-truncated values; refactoring that dropped the header name but left the prefix.

Related errors

• format of header must be header.k=v, 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/1d0e5b3f3fdc7a6c. Report an issue: GitHub.