hibiken/asynq · error

queue name must contain one or more characters

Error message

queue name must contain one or more characters

What it means

base.ValidateQueueName returns this error when the queue name is empty or contains only whitespace. Queue names are used to construct Redis keys, so a zero-length name would be ambiguous/unsafe and is rejected up front by Inspector methods and option composition.

Solutions

1. Trim and check the name before the API call: if strings.TrimSpace(q) == "" use a default like "default".
2. Fix the config/env/flag source so the queue name is always populated.
3. Call base.ValidateQueueName(qname) as an explicit pre-check with a clear user-facing message.

Example fix

// before
info, err := insp.GetQueueInfo(os.Getenv("QUEUE"), nil)
// after
q := os.Getenv("QUEUE")
if strings.TrimSpace(q) == "" { q = "default" }
info, err := insp.GetQueueInfo(q, nil)

if err := base.ValidateQueueName(qname); err != nil { return err }

func validQueue(q string) bool { return strings.TrimSpace(q) != "" }

When it happens

Trigger: Calling Inspector.GetQueueInfo/History/ListPendingTasks/ListActiveTasks/ListAggregatingTasks or composing asynq options with qname == "" or " ".

Common situations: Missing env var or config entry for the queue name; empty CLI flag; iterating a map where a queue key had an empty value; calling before any queue was configured.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• asynq
• asynq: err
• task ID cannot be empty
• Unique TTL cannot be less than 1s
• group key cannot be empty

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

Appendix: source

Thrown at internal/base/base.go:100

	case "scheduled":
		return TaskStateScheduled, nil
	case "retry":
		return TaskStateRetry, nil
	case "archived":
		return TaskStateArchived, nil
	case "completed":
		return TaskStateCompleted, nil
	case "aggregating":
		return TaskStateAggregating, nil
	}
	return 0, errors.E(errors.FailedPrecondition, fmt.Sprintf("%q is not supported task state", s))
}

// ValidateQueueName validates a given qname to be used as a queue name.
// Returns nil if valid, otherwise returns non-nil error.
func ValidateQueueName(qname string) error {
	if len(strings.TrimSpace(qname)) == 0 {
		return fmt.Errorf("queue name must contain one or more characters")
	}
	return nil
}

// QueueKeyPrefix returns a prefix for all keys in the given queue.
func QueueKeyPrefix(qname string) string {
	return "asynq:{" + qname + "}:"
}

// TaskKeyPrefix returns a prefix for task key.
func TaskKeyPrefix(qname string) string {
	return QueueKeyPrefix(qname) + "t:"
}

// TaskKey returns a redis key for the given task message.
func TaskKey(qname, id string) string {
	return TaskKeyPrefix(qname) + id
}

View on GitHub (pinned to d135f1439b)