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

Reduce the path to a single DB-number segment: redis://host:6379/0.

redis: invalid URL path: %s

Error message

redis: invalid URL path: %s

What it means

Returned by setupTCPConn when the URL path contains more than one slash-delimited segment (e.g. /0/1). Only zero or one DB-number segment is permitted in a redis:// URL path; anything deeper is treated as malformed.

Source

Thrown at options.go:703

	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:
		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)
	}

	if u.Scheme == "rediss" {
		o.TLSConfig = &tls.Config{
			ServerName: h,
			MinVersion: tls.VersionTLS12,
		}
	}

	return setupConnParams(u, o)
}

// getHostPortWithDefaults is a helper function that splits the url into
// a host and a port. If the host is missing, it defaults to localhost
// and if the port is missing, it defaults to 6379.
func getHostPortWithDefaults(u *url.URL) (string, string) {
	// u.Hostname and u.Port strip the surrounding brackets from IPv6 literals
	// (e.g. "[::1]" -> "::1") and handle the missing-port case, which

View on GitHub (pinned to 36d97525cd)

Solutions

Reduce the path to a single DB-number segment: redis://host:6379/0.
Drop the path and pass the DB via ?db=N or Options.DB.
Normalise/validate the URL string before calling ParseURL.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

func singleSegmentPath(p string) bool {
    return len(strings.FieldsFunc(p, func(r rune) bool { return r == '/' })) <= 1
}

Prevention

Never join extra path components onto a redis:// URL.
Pass DB via ?db=N if you need a clean empty path.
Validate the URL path has at most one segment before ParseURL.

When it happens

Trigger: Passing redis://host:6379/0/1, redis://host:6379/a/b, or any URL whose path has multiple segments. Often from appending extra path components meant for an HTTP-style router.

Common situations: Building the URL by joining path parts, a load-balancer/proxy that rewrites the path, or accidentally including a trailing segment.

Related errors

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