grafana/k6 · error

proxy.server must be set

Error message

proxy.server must be set

What it means

Validation error from ProxyOptions.Validate: a proxy block was supplied for a browser context but its server field is empty (or whitespace-only). k6 requires the CDP endpoint of the proxy to be configured whenever the proxy option is present — supplying the block at all signals intent, and an empty server is treated as a configuration mistake. A nil proxy block passes validation.

Source

Thrown at internal/js/modules/k6/browser/common/browser_context_options.go:68

type Geolocation struct {
	Latitude  float64 `js:"latitude"`
	Longitude float64 `js:"longitude"`
	Accuracy  float64 `js:"accuracy"`
}

// ProxyOptions represents proxy configuration for a browser context.
type ProxyOptions struct {
	Server string `js:"server"`
	Bypass string `js:"bypass"`
}

// Validate validates the [ProxyOptions].
func (p *ProxyOptions) Validate() error {
	if p == nil {
		return nil
	}
	if strings.TrimSpace(p.Server) == "" {
		return fmt.Errorf("proxy.server must be set")
	}
	return nil
}

// Validate validates the [Geolocation].
func (g *Geolocation) Validate() error {
	if g.Longitude < -180 || g.Longitude > 180 {
		return fmt.Errorf(`invalid longitude "%.2f": precondition -180 <= LONGITUDE <= 180 failed`, g.Longitude)
	}
	if g.Latitude < -90 || g.Latitude > 90 {
		return fmt.Errorf(`invalid latitude "%.2f": precondition -90 <= LATITUDE <= 90 failed`, g.Latitude)
	}
	if g.Accuracy < 0 {
		return fmt.Errorf(`invalid accuracy "%.2f": precondition 0 <= ACCURACY failed`, g.Accuracy)
	}
	return nil
}

View on GitHub (pinned to 93accf6570)

Solutions

1. Set server to the proxy endpoint: proxy: { server: 'http://myproxy.corp:8080' }.
2. If you don't need a proxy, remove the proxy block entirely (an absent block is valid; an empty one is not).
3. When proxy config comes from env vars, fail fast with a clear message when the variable is unset instead of passing an empty server.

Example fix

// before
const context = browser.newContext({ proxy: { bypass: 'localhost' } });

// after
const context = browser.newContext({
  proxy: { server: 'http://myproxy:8080', bypass: 'localhost' },
});

const proxyOpts = proxyServerFromEnv ? { server: proxyServerFromEnv, bypass } : undefined;
if (proxyOpts && !String(proxyOpts.server).trim()) {
  throw new Error('proxy.server must be a non-empty proxy URL, e.g. http://proxy:8080');
}
browser.newContext({ proxy: proxyOpts });

function isUsableProxyOptions(p) {
  return p == null || (typeof p.server === 'string' && p.server.trim() !== '');
}

When it happens

Trigger: browser.newContext({ proxy: {} }), { proxy: { bypass: 'localhost' } }, or proxy: { server: ' ' }. Also triggered when server is set via a variable that resolves to an empty string.

Common situations: Config scaffolding where the proxy option is added before the proxy URL is actually wired in; env-driven proxy config where the variable name is misspelled and yields ''; copying an example that only showed the bypass field.

Related errors

• 104
• unexpected HTTP error from %s: %d %s
• failed to parse retryable status codes: %w
• invalid stack URL: %w
• stack ID %d overflows int32

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