What causes "redis: invalid URL scheme: %s" in redis/go-redis?

Change the URL scheme to redis:// (no TLS) or rediss:// (TLS)

redis: invalid URL scheme: %s

Error message

redis: invalid URL scheme: %s

What it means

ParseFailoverURL (via setupFailoverConn) only accepts URL schemes "redis" and "rediss" when parsing a Redis Sentinel failover connection URL. Any other scheme (e.g. "http", "", "sentinel", or a mistyped "redis" spelling) fails with this error. "rediss" enables TLS with a config keyed to the URL host.

Source

Thrown at sentinel.go:441

	}
	return setupFailoverConn(u)
}

func setupFailoverConn(u *url.URL) (*FailoverOptions, error) {
	o := &FailoverOptions{}

	o.SentinelUsername, o.SentinelPassword = getUserPassword(u)

	h, p := getHostPortWithDefaults(u)
	o.SentinelAddrs = append(o.SentinelAddrs, net.JoinHostPort(h, p))

	switch u.Scheme {
	case "rediss":
		o.TLSConfig = &tls.Config{ServerName: h, MinVersion: tls.VersionTLS12}
	case "redis":
		o.TLSConfig = nil
	default:
		return nil, fmt.Errorf("redis: invalid URL scheme: %s", u.Scheme)
	}

	f := strings.FieldsFunc(u.Path, func(r rune) bool {
		return r == '/'
	})
	switch len(f) {
	case 0:
		o.DB = 0
	case 1:
		var err error
		if o.DB, err = strconv.Atoi(f[0]); err != nil {
			return nil, fmt.Errorf("redis: invalid database number: %q", f[0])
		}
	default:
		return nil, fmt.Errorf("redis: invalid URL path: %s", u.Path)
	}

	return setupFailoverConnParams(u, o)

View on GitHub (pinned to c5cad058c7)

Solutions

Change the URL scheme to redis:// (no TLS) or rediss:// (TLS)
Check the string for typos: redsi://, redis:/, or a missing // after the scheme all break url.Parse's scheme detection
If you need a custom scheme, pre-rewrite it with strings.Replace before calling ParseFailoverURL

Example fix

// before
opt, err := redis.ParseFailoverURL("sentinel://mymaster:26379")
// after
opt, err := redis.ParseFailoverURL("redis://mymaster:26379")

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(raw)
if err != nil { return err }
if u.Scheme != "redis" && u.Scheme != "rediss" {
    return fmt.Errorf("scheme must be redis or rediss, got %q", u.Scheme)
}

Try / catch

opt, err := redis.ParseFailoverURL(raw)
if err != nil {
    return fmt.Errorf("parsing failover URL %q: %w", raw, err)
}

Prevention

Only use redis:// or rediss:// for go-redis failover URLs
Verify the scheme survives config templating (no empty scheme)
Use rediss:// when TLS is required

When it happens

Trigger: Calling redis.ParseFailoverURL with a URL whose scheme is not redis/rediss, e.g. ParseFailoverURL("sentinel://host:26379?addr=...") or ParseFailoverURL("http://...").

Common situations: Copy-pasting a connection string from a dashboard or other service that uses a non-redis scheme, forgetting the scheme prefix (empty scheme), or assuming a "sentinel" scheme exists for failover URLs.

Related errors

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/c26eb160290ad0db. Report an issue: GitHub.