What causes "queue %q is not a valid queue" in nats-io/nats-server?

Replace the queue portion with a valid subject token (letters, digits, '-', '_', '.', no wildcards or spaces)

queue %q is not a valid queue

Error message

queue %q is not a valid queue

What it means

This error comes from NATS server option validation when parsing a colon-separated queue subscription string ('subject:queue') supplied in options (e.g. service imports/exports or queue placeholders). It means the second element, the queue/group name, is not a valid NATS subject token per IsValidSubject. The library rejects it early so an invalid queue name never reaches the routing layer.

Source

Thrown at server/opts.go:5065

	}
	return p, nil
}

// Helper function to validate permissions subjects.
func checkPermSubjectArray(sa []string, allowQueue bool) error {
	for _, s := range sa {
		if !IsValidSubject(s) {
			if !allowQueue {
				return fmt.Errorf("subject %q is not a valid subject", s)
			}
			// Check here if this is a queue group qualified subject.
			elements := strings.Fields(s)
			if len(elements) != 2 {
				return fmt.Errorf("subject %q is not a valid subject", s)
			} else if !IsValidSubject(elements[0]) {
				return fmt.Errorf("subject %q is not a valid subject", elements[0])
			} else if !IsValidSubject(elements[1]) {
				return fmt.Errorf("queue %q is not a valid queue", elements[1])
			}
		}
	}
	return nil
}

// PrintTLSHelpAndDie prints TLS usage and exits.
func PrintTLSHelpAndDie() {
	fmt.Printf("%s", tlsUsage)
	for k := range cipherMap {
		fmt.Printf("    %s\n", k)
	}
	fmt.Printf("\nAvailable curve preferences include:\n")
	for k := range curvePreferenceMap {
		fmt.Printf("    %s\n", k)
	}
	if runtime.GOOS == "windows" {
		fmt.Printf("%s\n", certstore.Usage)

View on GitHub (pinned to 3a66a489d2)

Solutions

Replace the queue portion with a valid subject token (letters, digits, '-', '_', '.', no wildcards or spaces)
Check the config file line for stray whitespace or special characters in the queue name
Validate the string with server.IsValidSubject(elements[1]) before handing it to the options parser

Example fix

// before: 'foo.bar.*:my queue'  -> invalid queue
// after
srv, err := server.NewServer(&server.Options{
  // valid queue token
  // e.g. 'foo.bar:workers'
})

Defensive patterns

Strategy: validation

Validate before calling

for _, part := range strings.Split(s, ":") {
  if !server.IsValidSubject(part) {
    return fmt.Errorf("invalid subject/queue token %q", part)
  }
}

Type guard

func isValidQueue(q string) bool { return q != "" && server.IsValidSubject(q) }

Prevention

Never use wildcards (*, >) or spaces in queue group names
Validate subject:queue strings at config-load time
Keep queue names simple alphanumeric tokens

When it happens

Trigger: Calling ProcessOptions/Parse with a config entry containing 'subject:queue' where the part after the first ':' contains wildcards ('*','>'), invalid characters (spaces, ':', non-ASCII), or is empty.

Common situations: Typos in queue group names in nats-server config files; accidentally passing a full multi-token subject where a queue name is expected; copying a subscription string like 'foo.bar.*:workers' where '*' is invalid in a queue name.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/cfdbd3d41bb090ce. Report an issue: GitHub.