grafana/k6 · error

WebSocket requires valid url, but got %q which resulted in %

Error message

WebSocket requires valid url, but got %q which resulted in %w

What it means

Validation failure in the WebSocket constructor's URL parsing: the first argument was a non-null string, but Go's net/url.Parse rejected it as malformed. This is the k6-side equivalent of the browser's SyntaxError for an unparseable WebSocket URL — control characters, spaces, invalid percent-encoding, or a missing scheme are typical culprits, and the wrapped %w carries url.Parse's exact reason.

Source

Thrown at internal/js/modules/k6/websockets/websockets.go:181

	// Maybe have this after the goroutine below ?!?
	defineWebsocket(rt, w)

	go w.establishConnection(params)
	return w.obj
}

// parseURL parses the url from the first constructor calls argument or returns an error
func parseURL(urlValue sobek.Value) (*url.URL, error) {
	if common.IsNullish(urlValue) {
		return nil, errors.New("WebSocket requires a url")
	}

	// TODO: throw the SyntaxError (https://websockets.spec.whatwg.org/#dom-websocket-websocket)
	urlString := urlValue.String()
	url, err := url.Parse(urlString)
	if err != nil {
		return nil, fmt.Errorf("WebSocket requires valid url, but got %q which resulted in %w", urlString, err)
	}
	if url.Scheme != "ws" && url.Scheme != "wss" {
		return nil, fmt.Errorf("WebSocket requires url with scheme ws or wss, but got %q", url.Scheme)
	}
	if url.Fragment != "" {
		return nil, fmt.Errorf("WebSocket requires no url fragment, but got %q", url.Fragment)
	}

	return url, nil
}

const (
	arraybufferBinaryType = "arraybuffer"
	blobBinaryType        = "blob"
)

// defineWebsocket defines all properties and methods for the WebSocket
func defineWebsocket(rt *sobek.Runtime, w *webSocket) {

View on GitHub (pinned to 165bb3c1a4)

Solutions

1. Check the URL string for typos, stray spaces, quotes, or control characters
2. Percent-encode any special characters in the URL before passing it to new WebSocket
3. Ensure the URL includes a scheme, e.g., ws:// or wss://
4. Log the exact value passed to the constructor to spot script-side string interpolation bugs

When it happens

Trigger: Thrown at internal/js/modules/k6/websockets/websockets.go:170 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grafana/k6@165bb3c1a4 (2026-08-18). Data as JSON: /api/errors/cb83157966047985. Report an issue: GitHub.