grafana/k6 · error

unqouting K6_INSTANCE_SCENARIOS

Error message

unqouting K6_INSTANCE_SCENARIOS: %w

What it means

Thrown by the k6 browser registry at startup when the K6_INSTANCE_SCENARIOS environment variable is defined and non-empty but strconv.Unquote cannot parse it as a Go-quoted string. The variable is an internal coordination channel (set by k6 when browser scenarios run with a remote/browser cloud setup) carrying a double-quoted, escape-encoded JSON payload; a raw unquoted JSON value fails unquoting.

Solutions

1. Unset K6_INSTANCE_SCENARIOS unless k6 itself is orchestrating the run: the local browser module works without it.
2. If you must emulate it, wrap the JSON in Go-style double quotes with escaped inner quotes so strconv.Unquote succeeds.
3. Verify the exact value with a print of the env var before launch to spot mangling by Docker/CI.
4. Upgrade k6 to a matching version so launcher and browser module agree on the variable's format.

Example fix

# before
export K6_INSTANCE_SCENARIOS='[{"id":"s1","browsers":[{"handle":"ws://host"}]}]'

# after (unset for local runs)
unset K6_INSTANCE_SCENARIOS
# or, if emulating the internal format:
export K6_INSTANCE_SCENARIOS='"[{\"id\":\"s1\",\"browsers\":[{\"handle\":\"ws://host\"}]}]"'

# Only k6 itself should set this; verify it is either absent or a Go-quoted string
if [ -n "$K6_INSTANCE_SCENARIOS" ] && [ "${K6_INSTANCE_SCENARIOS:0:1}" != '"' ]; then
  echo "K6_INSTANCE_SCENARIOS must be unset or a quoted payload" >&2
  exit 1
fi
k6 run script.js

When it happens

Trigger: Manually exporting K6_INSTANCE_SCENARIOS='[{"id":"x",...}]' (raw JSON, no outer Go quotes); double-quoting inconsistencies or trailing backslashes that break escape sequences; env injection tools (Docker ENV, CI secrets) that mangle inner quotes.

Common situations: Trying to simulate or debug remote-browser orchestration locally by hand-setting the variable; wrapper scripts or CI templates that JSON-encode the value twice or not at all; version changes in how k6 passes scenario metadata between processes.

Related errors

• parsing
• browser not found in registry. make sure to set browser…
• 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/9f614ec54663fcdc. Report an issue: GitHub.

Appendix: source

Thrown at internal/js/modules/k6/browser/browser/registry.go:126

	}

	return true, parts
}

// checkForScenarios will parse the K6_INSTANCE_SCENARIOS env var if
// it has been defined.
func checkForScenarios(envLookup env.LookupFunc) (bool, []string, error) {
	scenariosJSON, isRemote := envLookup(env.InstanceScenarios)
	if !isRemote {
		return false, nil, nil
	}
	// prevent failing in unquoting empty string.
	if scenariosJSON == "" {
		return false, nil, nil
	}
	scenariosJSON, err := strconv.Unquote(scenariosJSON)
	if err != nil {
		return false, nil, fmt.Errorf("unqouting K6_INSTANCE_SCENARIOS: %w", err)
	}

	var scenarios []struct {
		ID       string `json:"id"`
		Browsers []struct {
			Handle string `json:"handle"`
		} `json:"browsers"`
	}
	if err := json.Unmarshal([]byte(scenariosJSON), &scenarios); err != nil {
		return false, nil, fmt.Errorf("parsing K6_INSTANCE_SCENARIOS: %w", err)
	}

	var wsURLs []string
	for _, s := range scenarios {
		for _, b := range s.Browsers {
			if strings.TrimSpace(b.Handle) == "" {
				continue
			}

View on GitHub (pinned to 01ffac6f24)