nats-io/nats-server · error

total weight needs to be <= 100

Error message

total weight needs to be <= 100

What it means

Account subject-mapping validation: the summed weights of all destinations within a single cluster exceed 100 — weighted mappings must total at most 100 per cluster. The dests list (weights and cluster labels) passed to the mapping add is the input at fault; individual weights above 100 are rejected separately just before this check.

Source

Thrown at server/accounts.go:816

	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 {
				m.cdests = make(map[string][]*destination)
			}
			ad := m.cdests[d.Cluster]
			ad = append(ad, &destination{tr, d.Weight})

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Sum the weights per cluster and rebalance so each cluster totals <= 100.
2. Reduce individual entry weights proportionally to their desired traffic split.
3. Move overflow traffic to a different cluster entry.

Example fix

// before
dests = []WeightedDestination{{Cluster:"A",Subject:"s1",Weight:60},{Cluster:"A",Subject:"s2",Weight:60}}
// after
dests = []WeightedDestination{{Cluster:"A",Subject:"s1",Weight:60},{Cluster:"A",Subject:"s2",Weight:40}}

totals := map[string]int{}
for _, d := range dests {
    totals[d.Cluster] += d.Weight
    if totals[d.Cluster] > 100 {
        return fmt.Errorf("cluster %s exceeds 100%%", d.Cluster)
    }
}

if err := acc.AddMapping(...); err != nil {
    if strings.Contains(err.Error(), "total weight") {
        // rebalance cluster weights
    }
}

When it happens

Trigger: Adding multiple WeightedDestination entries for the same Cluster whose combined Weight sums to more than 100, via AddMapping or config load.

Common situations: Adding a second mapping entry for the same cluster without accounting for existing weights; splitting traffic 60/60 across two subjects on one cluster.

Related errors

• individual weights need 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/95b46b9d4b013dcf. Report an issue: GitHub.