nats-io/nats-server · error

generated invalid subject %q: %q is not defined

Error message

generated invalid subject %q: %q is not defined

What it means

A {{tag:name}} template in a permission subject resolved to no matching account tag (no tag with that prefix exists), and because failOnBadSubject is set the invalid generated subject is rejected instead of being silently dropped.

Source

Thrown at server/auth.go:579

					if match[0] == "account-tag" {
						acc.mu.RLock()
						tags = acc.tags
						acc.mu.RUnlock()
					} else {
						tags = ujwt.Tags
					}
					tagPrefix := fmt.Sprintf("%s:", strings.ToLower(match[1]))
					var valueList []string
					for _, tag := range tags {
						if strings.HasPrefix(tag, tagPrefix) {
							tagValue := strings.TrimPrefix(tag, tagPrefix)
							valueList = append(valueList, tagValue)
						}
					}
					if len(valueList) != 0 {
						values[tokenNum] = valueList
					} else if failOnBadSubject {
						return nil, fmt.Errorf("generated invalid subject %q: %q is not defined", list[i], match[1])
					} else {
						// generate an invalid subject?
						values[tokenNum] = []string{" "}
					}
				} else {
					return nil, fmt.Errorf("template operation in %q: %q is not defined", list[i], op)
				}
			}
			if !hasTags {
				subj := list[i]
				for idx, m := range srcs {
					subj = strings.Replace(subj, m, values[idx][0], -1)
				}
				if IsValidSubject(subj) {
					emittedList = append(emittedList, subj)
				} else if failOnBadSubject {
					return nil, fmt.Errorf("generated invalid subject")
				}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add the missing tag to the account claims so the template resolves
2. Remove or correct the template token in the permission subject
3. Ensure the signing account actually scopes the expected tags

When it happens

Trigger: Thrown at server/auth.go:579 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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