nats-io/nats-server · error

template expansion exceeds limit

Error message

template expansion exceeds limit

What it means

Wrapped sentinel errPermTemplateExpansionLimit: expanding mustache-style {{tag:x}} templates in a permission subject (or subscription/response templates) would produce a cartesian product exceeding maxPermTemplateSubjectExpansions, so the expansion is aborted to bound memory/CPU.

Source

Thrown at server/auth.go:476

	}
	tlsState := c.GetTLSConnectionState()
	if tlsState == nil || len(tlsState.PeerCertificates) == 0 || tlsState.PeerCertificates[0] == nil {
		c.Debugf("Failed pinned cert test as client did not provide a certificate")
		return false
	}
	sha := sha256.Sum256(tlsState.PeerCertificates[0].RawSubjectPublicKeyInfo)
	keyId := hex.EncodeToString(sha[:])
	if _, ok := tlsPinnedCerts[keyId]; !ok {
		c.Debugf("Failed pinned cert test for key id: %s", keyId)
		return false
	}
	return true
}

var (
	mustacheRE                             = regexp.MustCompile(`{{2}([^}]+)}{2}`)
	maxPermTemplateSubjectExpansions       = 4096
	errPermTemplateExpansionLimit    error = fmt.Errorf("template expansion exceeds limit")
)

func processUserPermissionsTemplate(lim jwt.UserPermissionLimits, ujwt *jwt.UserClaims, acc *Account) (jwt.UserPermissionLimits, error) {
	nArrayCartesianProduct := func(a ...[]string) [][]string {
		c := 1
		for _, a := range a {
			c *= len(a)
		}
		if c == 0 {
			return nil
		}
		p := make([][]string, c)
		b := make([]string, c*len(a))
		n := make([]int, len(a))
		s := 0
		for i := range p {
			e := s + len(a)
			pi := b[s:e]

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Reduce the number of distinct template tokens in the permission subject
2. Narrow the account tags so fewer values match each {{tag:...}} prefix
3. Split the permission across multiple explicit subjects instead of one heavily templated subject

When it happens

Trigger: Thrown at server/auth.go:476 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/81239269be25708b. Report an issue: GitHub.