hibiken/asynq · critical

inspeq: unsupported RedisConnOpt type %T

Error message

inspeq: unsupported RedisConnOpt type %T

What it means

asynq.NewInspector panics when the given RedisConnOpt's MakeRedisClient() does not yield a redis.UniversalClient. The Inspector requires a go-redis UniversalClient to perform its Redis-backed inspection commands, and any incompatible connection-option implementation causes this immediate panic instead of a returned error.

Solutions

1. Use asynq.RedisClientOpt, RedisClusterClientOpt, or RedisFailoverClientOpt when creating the Inspector
2. If you already have a go-redis UniversalClient, call asynq.NewInspectorFromRedisClient instead
3. Make your custom RedisConnOpt's MakeRedisClient return a value implementing redis.UniversalClient
4. Verify go-redis version compatibility (the UniversalClient interface must match what asynq was built against)

Example fix

// before
inspector := asynq.NewInspector(myRedigoBasedOpt{})

// after
inspector := asynq.NewInspector(asynq.RedisClientOpt{Addr: "localhost:6379"})

opt := asynq.RedisClientOpt{Addr: ":6379"}
if _, ok := opt.MakeRedisClient().(redis.UniversalClient); !ok {
    log.Fatal("inspector conn opt must yield redis.UniversalClient")
}
inspector := asynq.NewInspector(opt)

func connOptIsUniversalClient(r asynq.RedisConnOpt) bool {
    _, ok := r.MakeRedisClient().(redis.UniversalClient)
    return ok
}

When it happens

Trigger: Constructing asynq.NewInspector with a custom RedisConnOpt whose MakeRedisClient returns nil or a non-go-redis client; passing a wrapper type; a third-party conn option that doesn't adapt to asynq's expected interface.

Common situations: Copy-pasting a config object built for another Redis library (e.g. redigo conn) into asynq; custom conn opts that return *redis.Client from an incompatible go-redis major version; misconfiguring DI containers that supply the wrong type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

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

Appendix: source

Thrown at inspector.go:33

	"github.com/hibiken/asynq/internal/errors"
	"github.com/hibiken/asynq/internal/rdb"
	"github.com/redis/go-redis/v9"
)

// Inspector is a client interface to inspect and mutate the state of
// queues and tasks.
type Inspector struct {
	rdb *rdb.RDB
	// When an Inspector has been created with an existing Redis connection, we do
	// not want to close it.
	sharedConnection bool
}

// New returns a new instance of Inspector.
func NewInspector(r RedisConnOpt) *Inspector {
	c, ok := r.MakeRedisClient().(redis.UniversalClient)
	if !ok {
		panic(fmt.Sprintf("inspeq: unsupported RedisConnOpt type %T", r))
	}
	inspector := NewInspectorFromRedisClient(c)
	inspector.sharedConnection = false
	return inspector
}

// NewInspectorFromRedisClient returns a new instance of Inspector given a redis.UniversalClient
// Warning: The underlying redis connection pool will not be closed by Asynq, you are responsible for closing it.
func NewInspectorFromRedisClient(c redis.UniversalClient) *Inspector {
	return &Inspector{
		rdb:              rdb.NewRDB(c),
		sharedConnection: true,
	}
}

// Close closes the connection with redis.
func (i *Inspector) Close() error {
	if i.sharedConnection {

View on GitHub (pinned to d135f1439b)