grafana/k6 · error

missing required url

Error message

missing required url

What it means

When K6_BROWSER_SCREENSHOTS_OUTPUT is set, the k6 browser module parses it as a comma-separated presigned-URL config `url=...,basePath=...,header.NAME=...` (parsePresignedURLEnvVar, internal/js/modules/k6/browser/browser/file_persister.go:41-100). The `url` entry is the only required one; if the variable is non-empty but contains no `url=` key, parsing fails with 'missing required url', surfaced as `parsing K6_BROWSER_SCREENSHOTS_OUTPUT: missing required url` when the browser module builds its screenshot persister.

Solutions

1. Set the full value: `K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://uploads.example.com/,basePath=/screenshots,header.Authorization=Bearer <token>"`
2. If you want screenshots saved to the local disk instead, unset K6_BROWSER_SCREENSHOTS_OUTPUT entirely (empty/missing falls back to LocalFilePersister)
3. Verify the format with a quick parse before the run: each comma-separated token must be exactly `key=value` with keys url, basePath, or header.NAME

Example fix

# before
export K6_BROWSER_SCREENSHOTS_OUTPUT="basePath=/screenshots"

# after
export K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://uploads.example.com/,basePath=/screenshots"

#!/usr/bin/env bash
# validate before launching k6
v="$K6_BROWSER_SCREENSHOTS_OUTPUT"
if [ -n "$v" ]; then
  case "$v" in
    url=*) ;;
    *,url=*) ;;
    *) echo "K6_BROWSER_SCREENSHOTS_OUTPUT must start with (or contain) url=<scheme>://<host>" >&2; exit 1;;
  esac
fi

When it happens

Trigger: Setting the env var with only optional keys, e.g. `K6_BROWSER_SCREENSHOTS_OUTPUT="basePath=/shots"` or `K6_BROWSER_SCREENSHOTS_OUTPUT="header.Authorization=Bearer x"`, or using `;`/space instead of `,` as separator so no `url=` token is recognized. A key with wrong case (`URL=`) hits 'invalid option' instead, so this error specifically means: variable set, no parseable `url=` entry at all.

Common situations: Migrating screenshots from local disk to remote storage in CI and forgetting the URL; env files where the value got truncated at an `=` or newline; assuming basePath alone is enough; copy-pasting an env var between CI systems that mangle commas.

Related errors

• parsing
• both K6_CLOUD_METRICS_PUSH_URL and K6_CLOUD_TEST_RUN_TOKEN…
• empty header key, received
• format of header must be header.k=v, received
• format of value must be k=v, received

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

Appendix: source

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

		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)
		}
	}

	if presignedURL.getterURL == "" {
		return presignedURLConfig{}, errors.New("missing required url")
	}

	return presignedURL, nil
}

View on GitHub (pinned to 01ffac6f24)