nats-io/nats-server · error

error setting up update handling: %v

Error message

error setting up update handling: %v

What it means

During setup of the directory-resolver update subscription, the server subscribes to the account update subject and registers a handler that saves the received JWT via dr.save. If s.sysSubscribe for that update handler fails (subscription setup error), the whole setup function aborts with 'error setting up update handling: %v', wrapping the underlying cause.

Source

Thrown at server/accounts.go:4540

				return
			}
			if claim, err := jwt.DecodeAccountClaims(string(msg)); err != nil {
				respondToUpdate(s, resp, "n/a", "jwt update resulted in error", err)
			} else if err := claimValidate(claim); err != nil {
				respondToUpdate(s, resp, claim.Subject, "jwt validation failed", err)
			} else if claim.Subject != pubKey {
				err := errors.New("subject does not match jwt content")
				respondToUpdate(s, resp, pubKey, "jwt update resulted in error", err)
			} else if claim.Issuer == op && strict {
				err := errors.New("operator requires issuer to be a signing key")
				respondToUpdate(s, resp, pubKey, "jwt update resulted in error", err)
			} else if err := dr.save(pubKey, string(msg)); err != nil {
				respondToUpdate(s, resp, pubKey, "jwt update resulted in error", err)
			} else {
				respondToUpdate(s, resp, pubKey, "jwt updated", nil)
			}
		}); err != nil {
			return fmt.Errorf("error setting up update handling: %v", err)
		}
	}
	if _, err := s.sysSubscribe(accClaimsReqSubj, func(_ *subscription, c *client, _ *Account, _, resp string, msg []byte) {
		// As this is a raw message, we need to extract payload and only decode claims from it,
		// in case request is sent with headers.
		_, msg = c.msgParts(msg)
		if claim, err := jwt.DecodeAccountClaims(string(msg)); err != nil {
			respondToUpdate(s, resp, "n/a", "jwt update resulted in error", err)
		} else if claim.Issuer == op && strict {
			err := errors.New("operator requires issuer to be a signing key")
			respondToUpdate(s, resp, claim.Subject, "jwt update resulted in error", err)
		} else if err := claimValidate(claim); err != nil {
			respondToUpdate(s, resp, claim.Subject, "jwt validation failed", err)
		} else if err := dr.save(claim.Subject, string(msg)); err != nil {
			respondToUpdate(s, resp, claim.Subject, "jwt update resulted in error", err)
		} else {
			respondToUpdate(s, resp, claim.Subject, "jwt updated", nil)
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped %v cause in the error for the actual subscribe failure and fix that.
2. Raise internal subscription limits or reduce per-server subscription pressure.
3. Retry server start; check logs around shutdown/reload races.

if err := startResolver(); err != nil {
    if strings.Contains(err.Error(), "error setting up update handling") {
        log.WithError(err).Error("resolver update sub failed; check internal sub limits / shutdown state")
        // retry start after fixing cause
    }
}

When it happens

Trigger: Calling resolver setup (server start or reload) where sysSubscribe for the account claims update subject fails — e.g. internal subscription limits exhausted, malformed internal subject, or server shutting down concurrently.

Common situations: max_subscriptions / internal sub limits hit on busy servers; races during server shutdown/reload; resource exhaustion preventing new internal subscriptions.

Related errors

• error setting up lookup request handling: %v
• account jwt not found
• subject has exceeded number of tokens limit
• no operator key found
• auth callout violation: auth callout response is not for exp

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