nats-io/nats-server · error

subscribe allow: %w

Error message

subscribe allow: %w

What it means

Validation of a permission's subscribe allow list failed. The library wraps the underlying checkPermSubjectArray error with 'subscribe allow' to identify that the ALLOWED subscribe subjects in the Subscribe permission block are invalid. It is thrown during server config validation for authorization blocks, users, or account permission structures.

Source

Thrown at server/auth.go:1743

	}
	return validateNoAuthUser(o, o.NoAuthUser)
}

func validatePermissionSubjects(p *Permissions) error {
	if p == nil {
		return nil
	}
	if p.Publish != nil {
		if err := checkPermSubjectArray(p.Publish.Allow, false); err != nil {
			return fmt.Errorf("publish allow: %w", err)
		}
		if err := checkPermSubjectArray(p.Publish.Deny, false); err != nil {
			return fmt.Errorf("publish deny: %w", err)
		}
	}
	if p.Subscribe != nil {
		if err := checkPermSubjectArray(p.Subscribe.Allow, true); err != nil {
			return fmt.Errorf("subscribe allow: %w", err)
		}
		if err := checkPermSubjectArray(p.Subscribe.Deny, true); err != nil {
			return fmt.Errorf("subscribe deny: %w", err)
		}
	}
	return nil
}

func validateAllowedConnectionTypes(m map[string]struct{}) error {
	for ct := range m {
		ctuc := strings.ToUpper(ct)
		switch ctuc {
		case jwt.ConnectionTypeStandard, jwt.ConnectionTypeWebsocket,
			jwt.ConnectionTypeLeafnode, jwt.ConnectionTypeLeafnodeWS,
			jwt.ConnectionTypeMqtt, jwt.ConnectionTypeMqttWS,
			jwt.ConnectionTypeInProcess:
		default:
			return fmt.Errorf("unknown connection type %q", ct)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Correct the invalid subject string in Subscribe.Allow; the wrapped error identifies which one.
2. Re-check wildcard syntax: '*' matches exactly one token, '>' must be the final token.
3. Strip empty strings and whitespace-only entries from the allow array.
4. Test the config with `nats-server -t -c config` before deploying.

Example fix

// before
Subscribe: {Allow: []string{"foo..bar"}}
// after
Subscribe: {Allow: []string{"foo.*.bar"}}

for i, s := range perm.Subscribe.Allow {
    if s == "" { return fmt.Errorf("empty subscribe allow subject at %d", i) }
    if strings.Count(s, ">") > 1 { return fmt.Errorf("multiple > in %q", s) }
}

func validSubject(s string) bool {
    if s == "" { return false }
    parts := strings.Split(s, ".")
    for i, t := range parts {
        if t == "" { return false }
        if t == ">" && i != len(parts)-1 { return false }
    }
    return true
}

if err := validatePermissions(perms, true); err != nil {
    if strings.HasPrefix(err.Error(), "subscribe allow") {
        log.Fatalf("fix Subscribe.Allow subjects: %v", err)
    }
}

When it happens

Trigger: Calling validation with a Permissions struct whose Subscribe.Allow array contains malformed subjects — invalid wildcard placement, tokens with illegal characters, or empty entries — so checkPermSubjectArray(Subscribe.Allow, true) returns an error.

Common situations: Misconfigured nats_server.conf subscribe allow lists (e.g. 'foo.*.>' misuse or subjects like 'foo..bar'), programmatic user permission generation with bad inputs, or tooling that emits permissions from templates. Typically appears at startup or reload.

Related errors

• publish deny: %w
• subscribe deny: %w
• invalid connection types %q
• max_ack_pending must be set to -1
• bad sampling percentage, should be 1-100

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