hibiken/asynq · error

asynq: could not parse redis uri: database number should be…

Error message

asynq: could not parse redis uri: database number should be the first segment of the path

What it means

When parsing a redis:// or rediss:// URI, the first path segment must be the database number (e.g. /1 in redis://host:6379/1). This error is returned when that segment is not a valid integer. Note this variant is a plain error (no %w), so errors.Is against a sentinel is not possible.

Solutions

1. Put the numeric database number as the first path segment, e.g. redis://host:6379/0
2. Remove extra non-numeric path segments or move them to query parameters if intended
3. If no database selection is needed, omit the path entirely (defaults to db 0)

Example fix

// before
opt, err := asynq.ParseRedisURI("redis://localhost:6379/db0")
// after
opt, err := asynq.ParseRedisURI("redis://localhost:6379/0")

func validateRedisDBPath(uri string) error {
    u, err := url.Parse(uri)
    if err != nil {
        return err
    }
    if u.Path != "" {
        seg := strings.TrimPrefix(u.Path, "/")
        if i := strings.Index(seg, "/"); i >= 0 {
            seg = seg[:i]
        }
        if _, err := strconv.Atoi(seg); err != nil {
            return fmt.Errorf("first path segment %q must be a numeric db number", seg)
        }
    }
    return nil
}

opt, err := asynq.ParseRedisURI(uri)
if err != nil {
    if strings.Contains(err.Error(), "database number should be the first segment") {
        return fmt.Errorf("redis URI %q: use redis://host:port/<db> with a numeric db", uri)
    }
    return err
}

When it happens

Trigger: ParseRedisURI("redis://host:6379/notanumber") or any URI whose path starts with a non-numeric segment, e.g. redis://host/index0 or redis://host:6379/extra/path.

Common situations: Copy-pasting an HTTP-style path into a redis URI; putting the db in the query string instead of the path; trailing garbage after the db number; using a socket-style path form with the redis:// scheme.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• asynq: could not parse redis uri
• asynq: unsupported uri scheme
• asynq: unsupported RedisConnOpt type %T
• inspeq: unsupported RedisConnOpt type %T
• asynq: unsupported RedisConnOpt type %T

AI-assisted analysis of hibiken/asynq@d135f1439b (2026-09-07). Data as JSON: /api/errors/25a75f1f35cd2c91. Report an issue: GitHub.

Appendix: source

Thrown at asynq.go:502

	case "redis-socket":
		return parseRedisSocketURI(u)
	case "redis-sentinel":
		return parseRedisSentinelURI(u)
	default:
		return nil, fmt.Errorf("asynq: unsupported uri scheme: %q", u.Scheme)
	}
}

func parseRedisURI(u *url.URL) (RedisConnOpt, error) {
	var db int
	var err error
	var redisConnOpt RedisClientOpt

	if len(u.Path) > 0 {
		xs := strings.Split(strings.Trim(u.Path, "/"), "/")
		db, err = strconv.Atoi(xs[0])
		if err != nil {
			return nil, fmt.Errorf("asynq: could not parse redis uri: database number should be the first segment of the path")
		}
	}
	var password string
	if v, ok := u.User.Password(); ok {
		password = v
	}

	if u.Scheme == "rediss" {
		h, _, err := net.SplitHostPort(u.Host)
		if err != nil {
			h = u.Host
		}
		redisConnOpt.TLSConfig = &tls.Config{ServerName: h}
	}

	redisConnOpt.Addr = u.Host
	redisConnOpt.Password = password
	redisConnOpt.DB = db

View on GitHub (pinned to d135f1439b)