What causes "redis: invalid %s duration: %w" in go-redis/redis?

Use a Go duration string (5s, 250ms, 1m) or a bare integer for seconds.

redis: invalid %s duration: %w

Error message

redis: invalid %s duration: %w

What it means

Recorded on the queryOptions error slot by queryOptions.duration when a value is neither a plain integer (seconds) nor a valid time.ParseDuration string. Duration fields accept e.g. 5s, 250ms, or a bare integer of seconds; anything else is wrapped with the underlying parse error via %w.

Source

Thrown at options.go:809

	}
	// try plain number first
	if i, err := strconv.Atoi(s); err == nil {
		if i <= 0 {
			// disable timeouts
			return -1
		}
		return time.Duration(i) * time.Second
	}
	dur, err := time.ParseDuration(s)
	if err == nil {
		if dur <= 0 {
			// disable timeouts
			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
	}
}

View on GitHub (pinned to 36d97525cd)

Solutions

Use a Go duration string (5s, 250ms, 1m) or a bare integer for seconds.
Use a value <= 0 to disable the field where supported.
Remove the parameter to fall back to the default.

Example fix

// before
opt, err := redis.ParseURL("redis://localhost:6379/?dial_timeout=5sec")
// after
opt, err := redis.ParseURL("redis://localhost:6379/?dial_timeout=5s")

Defensive patterns

Strategy: validation

Validate before calling

func validDurationParam(s string) bool {
    if _, err := strconv.Atoi(s); err == nil { return true }
    _, err := time.ParseDuration(s); return err == nil
}

Prevention

Use Go duration units (s, ms, m) or a bare integer of seconds.
Avoid non-Go units like sec/min/day.
Centralise duration formatting in config helpers.

When it happens

Trigger: A URL like ?dial_timeout=5sec, ?read_timeout=fast, or ?conn_max_idle_time=1day (not a valid Go duration unit). The first bad duration parameter is the one reported.

Common situations: Using non-Go duration units (sec/min/day), missing the unit suffix on a non-integer, or pasting a value from a different client's config format.

Related errors

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