redis/go-redis · error

redis: invalid URL path: %s

Error message

redis: invalid URL path: %s

What it means

The URL path of a failover URL may contain at most one segment (the numeric database). If the path has more than one slash-separated segment, setupFailoverConn rejects it with this error. Empty paths are fine and mean DB 0.

Source

Thrown at sentinel.go:456

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

func setupFailoverConnParams(u *url.URL, o *FailoverOptions) (*FailoverOptions, error) {
	q := queryOptions{q: u.Query()}

	o.MasterName = q.string("master_name")
	o.ClientName = q.string("client_name")
	o.RouteByLatency = q.bool("route_by_latency")
	o.RouteByLatencyTolerance = q.duration("route_by_latency_tolerance")
	o.RouteRandomly = q.bool("route_randomly")
	o.ReplicaOnly = q.bool("replica_only")
	o.UseDisconnectedReplicas = q.bool("use_disconnected_replicas")
	o.Protocol = q.int("protocol")
	o.Username = q.string("username")
	o.Password = q.string("password")

View on GitHub (pinned to c5cad058c7)

Solutions

1. Keep only one numeric path segment: redis://host:26379/0
2. Move extra segments into query parameters that the parser supports (addr, db, skip_verify, etc.)
3. Strip the extra path components from the connection string

Example fix

// before
opt, err := redis.ParseFailoverURL("redis://host:26379/0/extra")
// after
opt, err := redis.ParseFailoverURL("redis://host:26379/0")

u, err := url.Parse(raw)
if err != nil { return err }
if strings.Count(strings.Trim(u.Path, "/"), "/") > 0 {
    return fmt.Errorf("failover URL path must have at most one segment, got %q", u.Path)
}

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

When it happens

Trigger: Calling ParseFailoverURL with a multi-segment path, e.g. redis://host:26379/0/extra or redis://host:26379/some/path/db.

Common situations: Pasting an HTTP-style URL that carries route segments in its path, or appending the master name and the DB to the path together.

Related errors

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

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