grafana/k6 · error

invalid browser command line flag: "%s=%v"

Error message

invalid browser command line flag: "%s=%v"

What it means

Returned by parseArgs (reached via BrowserType.launch -> allocate) when the flags map built for the Chrome command line contains a value that is neither a string nor a bool. Every internal flag in prepareFlags is a string or bool, so in practice this fires when a custom entry — typically from options.args handling or a host-resolver-rules style string — ends up as another Go type (int, float, nil, map) and Chrome args cannot be rendered for it.

Source

Thrown at internal/js/modules/k6/browser/chromium/browser_type.go:416

	}

	return "", ErrChromeNotInstalled
}

// parseArgs parses command-line arguments and returns them.
func parseArgs(flags map[string]any) ([]string, error) {
	// Build command line args list
	var args []string
	for name, value := range flags {
		switch value := value.(type) {
		case string:
			args = append(args, parseStringArg(name, value))
		case bool:
			if value {
				args = append(args, fmt.Sprintf("--%s", name))
			}
		default:
			return nil, fmt.Errorf(`invalid browser command line flag: "%s=%v"`, name, value)
		}
	}
	if _, ok := flags["remote-debugging-port"]; !ok {
		args = append(args, "--remote-debugging-port=0")
	}

	// Force the first page to be blank, instead of the welcome page;
	// --no-first-run doesn't enforce that.
	// args = append(args, common.BlankPage)
	// args = append(args, "--no-startup-window")
	return args, nil
}

func parseStringArg(flag string, value string) string {
	if strings.TrimSpace(value) == "" {
		// If the value is empty, we don't include it in the args list.
		// Otherwise, it will produce "--name=" which is invalid.
		return fmt.Sprintf("--%s", flag)

View on GitHub (pinned to 93accf6570)

Solutions

  1. Find the flag named in the error message (format is "name=value") and pass its value as a string, e.g. 'name=1024' in options.args
  2. Keep custom launch args as 'flag=value' strings in the args option — k6 parses them into string flags itself
  3. If you consume the Go API, ensure the map passed toward launch contains only bool or string values
  4. Report a k6 bug if no custom args are set — with stock options all internal flags are string/bool

Example fix

// before (custom Go glue sets a typed value)
flags["window-size"] = 1024

// after
flags["window-size"] = "1024,768"
Defensive patterns

Strategy: type-guard

Validate before calling

// Keep launch args as plain 'name=value' strings
const args = ['window-size=1280,800', 'disable-gpu'];
if (!args.every(a => typeof a === 'string' && /^[\w-]+(=.+)?$/.test(a))) {
  throw new Error('launch args must be strings of the form name[=value]');
}

Type guard

function isStringOrBoolFlag(v) {
  return typeof v === 'string' || typeof v === 'boolean';
}
// applies to Go consumers building the flags map:
// if (!isStringOrBoolFlag(flags[name])) return error

Try / catch

try {
  const browser = chromium.launch({ args });
} catch (e) {
  if (String(e.message).includes('invalid browser command line flag')) {
    // the message names the offending "name=value" pair; fix its type
    console.error('Flag values must be strings or booleans:', e.message);
  }
  throw e;
}

Prevention

When it happens

Trigger: chromium.launch() with an options value that flows a numeric flag into the flags map (e.g. a future/3rd-party option setting window-size as an int pair instead of the '800,600' string prepareFlags uses); programmatic use of the Go API putting an int/nil/struct value into the flags map consumed by allocate/parseArgs.

Common situations: Extensions or forks building flags maps programmatically and assuming any value type is accepted; k6 version drift where an option changed from string to typed value; scripts passing args like 'window-size=1024' that then get re-typed by custom glue code.

Related errors

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