hashicorp/nomad · error

unsupported scheme: %v

Error message

unsupported scheme: %v

What it means

In api/api.go:991, the websocket helper rewrites the request URL scheme http→ws and https→wss before dialing; any other scheme is rejected with this error. It means the websocket endpoint was reached with a URL scheme the client cannot translate to a websocket protocol.

Source

Thrown at api/api.go:991

	if err != nil {
		return nil, nil, err
	}
	r.setQueryOptions(q)

	rhttp, err := r.toHTTP()
	if err != nil {
		return nil, nil, err
	}

	// convert scheme
	wsScheme := ""
	switch rhttp.URL.Scheme {
	case "http":
		wsScheme = "ws"
	case "https":
		wsScheme = "wss"
	default:
		return nil, nil, fmt.Errorf("unsupported scheme: %v", rhttp.URL.Scheme)
	}
	rhttp.URL.Scheme = wsScheme

	conn, resp, err := dialer.Dial(rhttp.URL.String(), rhttp.Header)

	// check resp status code, as it's more informative than handshake error we get from ws library
	if resp != nil {
		switch resp.StatusCode {
		case http.StatusSwitchingProtocols:
			// Connection upgrade was successful.

		case http.StatusPermanentRedirect, http.StatusTemporaryRedirect, http.StatusMovedPermanently:
			loc := resp.Header.Get("Location")
			u, err := url.Parse(loc)
			if err != nil {
				return nil, nil, fmt.Errorf("invalid redirect location %q: %w", loc, err)
			}
			return c.websocket(u.Path, q)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the client Address to http:// or https:// — the client converts to ws/wss automatically
2. Fix NOMAD_ADDR / Config.Address scheme and retry
3. Check any reverse proxy in front of Nomad preserves the http/https scheme in forwarded URLs
4. If the scheme originates from a redirect target, verify the upstream advertises http/https locations

Example fix

// before
cfg.Address = "wss://nomad.example.com" // unsupported scheme
// after
cfg.Address = "https://nomad.example.com" // client upgrades to wss for websockets

u, err := url.Parse(cfg.Address)
if err != nil || (u.Scheme != "http" && u.Scheme != "https") {
	return fmt.Errorf("Address must use http(s), got scheme %q", u.Scheme)
}

func isHTTPOrHTTPS(addr string) bool {
	u, err := url.Parse(addr)
	return err == nil && (u.Scheme == "http" || u.Scheme == "https")
}

if err != nil && strings.Contains(err.Error(), "unsupported scheme") {
	return fmt.Errorf("use http:// or https:// in NOMAD_ADDR (ws/wss are derived automatically): %w", err)
}

When it happens

Trigger: Calling websocket-based APIs (exec streaming, logs streaming) when the client's Address uses a scheme other than http/https — e.g. ws://, wss://, or a garbled scheme from bad configuration.

Common situations: Setting NOMAD_ADDR to "wss://..." assuming the client speaks raw websocket; a misconfigured proxy or service mesh rewriting the scheme; typos like "htttp://" reaching this switch.

Related errors

• invalid address '%s': %v
• failed to send input: %w
• websocket closed before receiving exit code: %w
• unexpected HTTP transport: %T
• invalid redirect location %q: %w

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/e981a5887c61e8c0. Report an issue: GitHub.