go-redis/redis · error

redis: invalid URL scheme: %s

Error message

redis: invalid URL scheme: %s

What it means

Returned by setupClusterConn (used by ParseClusterURL) when the URL scheme is neither redis nor rediss. Cluster URLs do not support unix://, so the accepted set is narrower than the standalone ParseURL.

Source

Thrown at osscluster.go:361

	// setup username, password, and other configurations
	o, err = setupClusterConn(u, h, o)
	if err != nil {
		return nil, err
	}

	return o, nil
}

// setupClusterConn gets the username and password from the URL and the query parameters.
func setupClusterConn(u *url.URL, host string, o *ClusterOptions) (*ClusterOptions, error) {
	switch u.Scheme {
	case "rediss":
		o.TLSConfig = &tls.Config{ServerName: host}
		fallthrough
	case "redis":
		o.Username, o.Password = getUserPassword(u)
	default:
		return nil, fmt.Errorf("redis: invalid URL scheme: %s", u.Scheme)
	}

	// retrieve the configuration from the query parameters
	o, err := setupClusterQueryParams(u, o)
	if err != nil {
		return nil, err
	}

	return o, nil
}

// setupClusterQueryParams converts query parameters in u to option value in o.
func setupClusterQueryParams(u *url.URL, o *ClusterOptions) (*ClusterOptions, error) {
	q := queryOptions{q: u.Query()}

	o.Protocol = q.int("protocol")
	o.ClientName = q.string("client_name")
	o.MaxRedirects = q.int("max_redirects")

View on GitHub (pinned to 36d97525cd)

Solutions

1. Use redis:// or rediss:// for the cluster URL.
2. If you have a list of seed nodes, build *redis.ClusterOptions{Addrs: [...]} directly.
3. For unix sockets, construct ClusterOptions manually (cluster URLs do not support the unix scheme).

Example fix

// before
opt, err := redis.ParseClusterURL("unix:///var/run/redis.sock")
// after
opt, err := redis.ParseClusterURL("redis://node1:7000")

func validClusterScheme(rawURL string) bool {
    u, err := url.Parse(rawURL); if err != nil { return false }
    return u.Scheme == "redis" || u.Scheme == "rediss"
}

func isClusterURL(rawURL string) bool {
    u, err := url.Parse(rawURL); if err != nil { return false }
    return u.Scheme == "redis" || u.Scheme == "rediss"
}

When it happens

Trigger: Calling redis.ParseClusterURL with a scheme like unix://, http://, or a bare host:port. The default branch of the switch in setupClusterConn fires for anything but redis/rediss.

Common situations: Reusing a standalone REDIS_URL (which may be unix://) for a cluster client, omitting the scheme, or pasting an HTTP-style URL.

Related errors

• redis: unable to parse addr param: %s
• redis: unexpected option: %s
• redis: invalid URL scheme: %s
• redis: invalid database number: %q
• redis: invalid URL path: %s

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/a3659746195483a1.json. Report an issue: GitHub.