What causes "redis: empty unix socket path" in go-redis/redis?

Provide the socket path in the URL: 'unix:///var/run/redis/redis.sock?db=0' (note the three slashes: scheme:/// ).

redis: empty unix socket path

Error message

redis: empty unix socket path

What it means

Returned by setupUnixConn (options.go:741) when ParseURL is given a 'unix://' URL whose path is empty or whitespace-only. The unix socket path is the URL path component (e.g. '/var/run/redis/redis.sock'); without it there is no socket to dial, so ParseURL fails fast rather than producing a useless Options.

Source

Thrown at options.go:741

	// leaving the brackets on the host, which the caller's net.JoinHostPort
	// would wrap again and turn "redis://[::1]" into "[[::1]]:6379".
	host, port := u.Hostname(), u.Port()
	if host == "" {
		host = "localhost"
	}
	if port == "" {
		port = "6379"
	}
	return host, port
}

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

	if strings.TrimSpace(u.Path) == "" { // path is required with unix connection
		return nil, errors.New("redis: empty unix socket path")
	}
	o.Addr = u.Path
	o.Username, o.Password = getUserPassword(u)
	return setupConnParams(u, o)
}

type queryOptions struct {
	q   url.Values
	err error
}

func (o *queryOptions) has(name string) bool {
	return len(o.q[name]) > 0
}

func (o *queryOptions) string(name string) string {
	vs := o.q[name]
	if len(vs) == 0 {

View on GitHub (pinned to 36d97525cd)

Solutions

Provide the socket path in the URL: 'unix:///var/run/redis/redis.sock?db=0' (note the three slashes: scheme:///<path>).
If constructing Options directly (not via ParseURL), set Options.Network='unix' and Options.Addr to the socket path instead.
Validate the path is non-empty before calling ParseURL; surface a clearer application-level error.

Example fix

// before
opt, err := redis.ParseURL("unix://")
// -> 'redis: empty unix socket path'

// after
opt, err := redis.ParseURL("unix:///var/run/redis/redis.sock?db=0")
// or build Options directly:
// opt := &redis.Options{Network: "unix", Addr: "/var/run/redis/redis.sock"}

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(raw)
if err != nil { return nil, err }
if u.Scheme == "unix" && strings.TrimSpace(u.Path) == "" {
    return nil, fmt.Errorf("redis: empty unix socket path (got %q)", raw)
}
return redis.ParseURL(raw)

Try / catch

opt, err := redis.ParseURL(raw)
if err != nil && strings.Contains(err.Error(), "empty unix socket path") {
    // build Options directly instead
    opt = &redis.Options{Network: "unix", Addr: socketPath}
    err = nil
}

Prevention

Use the three-slash form: unix:///path/to/redis.sock.
Validate the path is non-empty before ParseURL.
Prefer building Options directly when the socket path comes from config.

When it happens

Trigger: Calling redis.ParseURL with 'unix://' (no path) or 'unix://?db=0' — the u.Path is empty after TrimSpace, so setupUnixConn returns this error. Reached via ParseURL's scheme switch at options.go:676-677.

Common situations: Building the URL from parts and forgetting to append the socket path; a config template with a placeholder that wasn't filled; using 'unix://host' style (unix sockets don't take a host, they take a path); trailing-slash-only 'unix:///' that gets trimmed.

Related errors

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