grafana/k6 · error

WebSocket requires url with scheme ws or wss, but got %q

Error message

WebSocket requires url with scheme ws or wss, but got %q

What it means

Scheme guard in the WebSocket constructor's URL parsing: the URL parsed successfully, but its scheme is neither ws nor wss. Passing an http://, https://, ftp://, or scheme-less URL to new WebSocket triggers this error, since the WebSocket protocol only operates over its own schemes.

Source

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

	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) {
	must(rt, w.obj.DefineDataProperty(
		"addEventListener", rt.ToValue(w.addEventListener), sobek.FLAG_FALSE, sobek.FLAG_FALSE, sobek.FLAG_TRUE))
	must(rt, w.obj.DefineDataProperty(

View on GitHub (pinned to 165bb3c1a4)

Solutions

1. Change the scheme to ws:// (plain) or wss:// (TLS) — e.g., https://example.com/ws becomes wss://example.com/ws
2. Derive the WebSocket URL from the page URL programmatically by replacing http with ws
3. Verify the endpoint is actually a WebSocket server before connecting

When it happens

Trigger: Thrown at internal/js/modules/k6/websockets/websockets.go:173 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/07b131e496347791. Report an issue: GitHub.