What causes "asynq: unsupported uri scheme: %q" in hibiken/asynq?

Use one of the supported schemes: redis, rediss, redis-socket, or redis-sentinel

asynq: unsupported uri scheme

Error message

asynq: unsupported uri scheme: %q

What it means

ParseRedisURI accepts only the schemes redis, rediss, redis-socket, and redis-sentinel; any other scheme yields this error at asynq.go:489. It reports the unsupported scheme via %q so it is easy to spot which scheme string was actually parsed.

Solutions

Use one of the supported schemes: redis, rediss, redis-socket, or redis-sentinel
If no scheme is present, prefix the URI with redis:// (a bare host:port parses with an empty scheme)
For connection options not expressible as a URI, construct RedisClientOpt directly instead of ParseRedisURI

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

func validateRedisScheme(uri string) error {
    u, err := url.Parse(uri)
    if err != nil {
        return err
    }
    switch u.Scheme {
    case "redis", "rediss", "redis-socket", "redis-sentinel":
        return nil
    default:
        return fmt.Errorf("unsupported scheme %q", u.Scheme)
    }
}

Try / catch

opt, err := asynq.ParseRedisURI(uri)
if err != nil {
    if strings.HasPrefix(err.Error(), "asynq: unsupported uri scheme") {
        return fmt.Errorf("redis URI %q must use redis/rediss/redis-socket/redis-sentinel scheme", uri)
    }
    return err
}

Prevention

Always include an explicit scheme in Redis URIs, even for localhost (redis://localhost:6379)
Keep a small allowlist check of schemes in your config loader
Use lowercase schemes; url.Parse does not lowercase and asynq matches exactly

When it happens

Trigger: Calling ParseRedisURI with a URI whose parsed scheme is not one of the four supported ones, e.g. http://, memcache://, or Redis cluster-style redis+cluster:// URIs.

Common situations: Passing a plain hostname without a scheme (url.Parse then reports scheme as empty after splitting on ':'); using a scheme from a different client library's config; typos like rediss:// vs rediss (extra characters) or capitalized schemes from docs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at asynq.go:489

//
//	redis://[:password@]host[:port][/dbnumber]
//	rediss://[:password@]host[:port][/dbnumber]
//	redis-socket://[:password@]path[?db=dbnumber]
//	redis-sentinel://[:password@]host1[:port][,host2:[:port]][,hostN:[:port]][/dbnumber][?master=masterName]
func ParseRedisURI(uri string) (RedisConnOpt, error) {
	u, err := url.Parse(uri)
	if err != nil {
		return nil, fmt.Errorf("asynq: could not parse redis uri: %w", err)
	}
	switch u.Scheme {
	case "redis", "rediss":
		return parseRedisURI(u)
	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

View on GitHub (pinned to d135f1439b)