redis: invalid %s boolean: expected true/false/1/0 or an emp

Error message

redis: invalid %s boolean: expected true/false/1/0 or an empty string, got %q

What it means

Recorded on the queryOptions error slot by queryOptions.bool when a boolean query parameter is not one of true/false/1/0 or empty. Boolean options (pool_fifo, read_only, route_randomly, skip_verify, etc.) accept only those literal strings; any other value is rejected with the offending token quoted.

Source

Thrown at options.go:822

			return -1
		}
		return dur
	}
	if o.err == nil {
		o.err = fmt.Errorf("redis: invalid %s duration: %w", name, err)
	}
	return 0
}

func (o *queryOptions) bool(name string) bool {
	switch s := o.string(name); s {
	case "true", "1":
		return true
	case "false", "0", "":
		return false
	default:
		if o.err == nil {
			o.err = fmt.Errorf("redis: invalid %s boolean: expected true/false/1/0 or an empty string, got %q", name, s)
		}
		return false
	}
}

func (o *queryOptions) remaining() []string {
	if len(o.q) == 0 {
		return nil
	}
	keys := slices.Collect(maps.Keys(o.q))
	slices.Sort(keys)
	return keys
}

// setupConnParams converts query parameters in u to option value in o.
func setupConnParams(u *url.URL, o *Options) (*Options, error) {
	q := queryOptions{q: u.Query()}

View on GitHub (pinned to 36d97525cd)

Solutions

Use exactly true or false (lowercase), or 1/0, or omit the parameter.
If the value is dynamic, normalise it to those literals before building the URL.
Set the boolean directly on *redis.Options instead of via the URL.

Example fix

// before
opt, err := redis.ParseURL("redis://localhost:6379/?pool_fifo=yes")
// after
opt, err := redis.ParseURL("redis://localhost:6379/?pool_fifo=true")

Defensive patterns

Strategy: validation

Validate before calling

func validBoolParam(s string) bool {
    switch s { case "true", "false", "1", "0", "": return true }
    return false
}

Prevention

Use exactly true/false or 1/0 for URL booleans.
Set booleans on *redis.Options directly when in doubt.
Normalise dynamic values to the accepted literals before URL building.

When it happens

Trigger: A URL like ?pool_fifo=yes, ?skip_verify=TRUE (uppercase is not accepted), ?route_randomly=on, or ?pool_fifo=t.

Common situations: Using shell-style truthy values (yes/on/t), different case, or a 1/0 variant the parser does not allow.

Related errors

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