nats-io/nats-server · error

individual weights need to be <= 100

Error message

individual weights need to be <= 100

What it means

Thrown by NATS server account mapping weight validation (server/accounts.go:812). When validating weighted destination mappings for an account's mapping, each individual destination weight must be a percentage <= 100. The server rejects the whole mapping as soon as any single entry exceeds 100.

Source

Thrown at server/accounts.go:812

func (a *Account) AddWeightedMappings(src string, dests ...*MapDest) error {
	a.mu.Lock()
	defer a.mu.Unlock()

	if !IsValidSubject(src) {
		return ErrBadSubject
	}

	m := &mapping{src: src, wc: subjectHasWildcard(src), dests: make([]*destination, 0, len(dests)+1)}
	seen := make(map[string]struct{})

	var tw = make(map[string]uint8)
	for _, d := range dests {
		if _, ok := seen[d.Subject]; ok {
			return fmt.Errorf("duplicate entry for %q", d.Subject)
		}
		seen[d.Subject] = struct{}{}
		if d.Weight > 100 {
			return fmt.Errorf("individual weights need to be <= 100")
		}
		tw[d.Cluster] += d.Weight
		if tw[d.Cluster] > 100 {
			return fmt.Errorf("total weight needs to be <= 100")
		}
		err := ValidateMapping(src, d.Subject)
		if err != nil {
			return err
		}
		tr, err := NewSubjectTransform(src, d.Subject)
		if err != nil {
			return err
		}
		if d.Cluster == _EMPTY_ {
			m.dests = append(m.dests, &destination{tr, d.Weight})
		} else {
			// We have a cluster scoped filter.
			if m.cdests == nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set each mapping weight to a value between 0 and 100.
2. Treat weights as percentages of total traffic for that cluster; ensure per-cluster totals also stay <= 100.
3. Validate config with nats server config validation before applying.

Example fix

// before
mappings.AddWeightedMapping(dests, WeightedDestination{Cluster: "A", Subject: "foo", Weight: 150})
// after
mappings.AddWeightedMapping(dests, WeightedDestination{Cluster: "A", Subject: "foo", Weight: 75})

for _, d := range dests {
    if d.Weight > 100 || d.Weight < 0 {
        return fmt.Errorf("weight %d out of range for %s", d.Weight, d.Subject)
    }
}

if err := acc.AddMapping(...); err != nil {
    if strings.Contains(err.Error(), "<= 100") {
        // clamp or reject config
    }
}

When it happens

Trigger: Calling account mapping APIs (e.g. AddMapping / NewWeightedMappings) with a WeightedMapping whose Weight field is > 100, or submitting a config with weight values over 100.

Common situations: Config typos like weight: 150, confusing weights (percent) with plain integers, or generating weights programmatically without bounding them.

Related errors

• total weight needs to be <= 100
• max_request_batch must be set if it's JetStream limits are s
• consumer name can not contain '.', '*', '>', '\', '/'
• consumer durable name can not contain '.', '*', '>', '\', '/
• gateway name cannot contain spaces

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