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

Prefix the address with redis:// (or rediss:// for TLS, unix:// for sockets).

redis: invalid URL scheme: %s

Error message

redis: invalid URL scheme: %s

What it means

Returned by ParseURL (standalone client) when the URL scheme is not one of redis, rediss (TLS), or unix. ParseURL switches on u.Scheme and falls through to this error for anything else, including missing schemes (empty string) or typos like 'rediss://'.

Source

Thrown at options.go:679

//		Addr:        "localhost:6789",
//		DB:          1,               // path "/3" was overridden by "&db=1"
//		DialTimeout: 3 * time.Second, // no time unit = seconds
//		ReadTimeout: 6 * time.Second,
//		MaxRetries:  2,
//	}
func ParseURL(redisURL string) (*Options, error) {
	u, err := url.Parse(redisURL)
	if err != nil {
		return nil, err
	}

	switch u.Scheme {
	case "redis", "rediss":
		return setupTCPConn(u)
	case "unix":
		return setupUnixConn(u)
	default:
		return nil, fmt.Errorf("redis: invalid URL scheme: %s", u.Scheme)
	}
}

func setupTCPConn(u *url.URL) (*Options, error) {
	o := &Options{Network: "tcp"}

	o.Username, o.Password = getUserPassword(u)

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

	f := strings.FieldsFunc(u.Path, func(r rune) bool {
		return r == '/'
	})
	switch len(f) {
	case 0:
		o.DB = 0
	case 1:

View on GitHub (pinned to 36d97525cd)

Solutions

Prefix the address with redis:// (or rediss:// for TLS, unix:// for sockets).
If you only have host:port, construct *redis.Options directly with Addr instead of ParseURL.
Sanitise REDIS_URL at startup and fail fast with a clear message if the scheme is wrong.

Example fix

// before
opt, err := redis.ParseURL("localhost:6379/0")
// after
opt, err := redis.ParseURL("redis://localhost:6379/0")

Defensive patterns

Strategy: validation

Validate before calling

func validRedisScheme(rawURL string) bool {
    u, err := url.Parse(rawURL)
    if err != nil { return false }
    switch u.Scheme { case "redis", "rediss", "unix": return true }
    return false
}

Type guard

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

Try / catch

opt, err := redis.ParseURL(raw)
if err != nil { /* fall back to redis.Options{Addr: host} or fail fast */ }

Prevention

Always include the scheme in REDIS_URL.
Prefer redis.Options{Addr: ...} when you only have host:port.
Validate REDIS_URL at startup, not on first command.

When it happens

Trigger: Calling redis.ParseURL with a string whose scheme is unrecognised, e.g. "http://...", "localhost:6379" (no scheme), or a scheme with a typo.

Common situations: Forgetting the redis:// prefix and passing a bare host:port, copy-pasting a URL from another driver (postgres://, memcached://), or an env var (REDIS_URL) populated with the wrong format.

Related errors

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