grafana/k6 · error

missing required url

Error message

missing required url

What it means

The k6 browser module decides how to persist screenshots by parsing the K6_BROWSER_SCREENSHOTS_OUTPUT environment variable. When that variable is set but none of its comma-separated k=v pairs uses the key 'url', parsePresignedURLEnvVar returns this error, which newScreenshotPersister wraps as 'parsing K6_BROWSER_SCREENSHOTS_OUTPUT: missing required url'. The url key is the only mandatory entry because it is the remote endpoint screenshots are uploaded to; basePath and header.N entries are optional. Browser module initialization fails fast, aborting the test run before any script executes.

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 93accf6570)

Solutions

1. Add the required url key as a k=v pair, e.g. K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://127.0.0.1:9000/,basePath=/screenshots"
2. Verify every pair is strictly key=value with no extra spaces or quotes inside the value; the parser rejects pairs without exactly one '='
3. If local disk persistence is intended, unset K6_BROWSER_SCREENSHOTS_OUTPUT entirely so newScreenshotPersister returns LocalFilePersister
4. Double-check key spelling and case: only url, basePath, and header.<name> are accepted; anything else yields 'invalid option'

Example fix

# before
export K6_BROWSER_SCREENSHOTS_OUTPUT="basePath=/screenshots,header.Authorization=Bearer t"

# after
export K6_BROWSER_SCREENSHOTS_OUTPUT="url=https://screenshots.example.com/,basePath=/screenshots,header.Authorization=Bearer t"

# Run before k6: fail early with a clear message
value="${K6_BROWSER_SCREENSHOTS_OUTPUT:-}"
if [ -n "$value" ] && ! printf '%s' "$value" | grep -qE '(^|,)url='; then
  echo "K6_BROWSER_SCREENSHOTS_OUTPUT must contain a url=... entry" >&2
  exit 1
fi

When it happens

Trigger: Setting K6_BROWSER_SCREENSHOTS_OUTPUT to a value containing only optional keys, e.g. 'basePath=/screenshots' or 'header.Authorization=token', or misspelling the key as 'uri=' or 'URL=' (keys are case-sensitive and matched exactly by the switch in parsePresignedURLEnvVar).

Common situations: Copying a remote-upload example config incompletely in CI pipelines, renaming or translating keys when moving between environments, or adding custom headers/basePath while forgetting the endpoint. Also appears when the variable is set to a placeholder value during environment provisioning.

Related errors

• parsing %s: %w
• browser not found in registry. make sure to set browser type
• WebSocket endpoint cannot be empty
• k6 couldn't detect google chrome or a chromium-supported bro
• browser type option must be set

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