nats-io/nats-server · error

preload account error for %q: %v

Error message

preload account error for %q: %v

What it means

One of the entries in `resolver_preload` failed JWT account-claims decoding. The value under key %q is not a valid account JWT (bad base64/JWS structure, truncated, or corrupt), so the server refuses to preload it and aborts option processing.

Source

Thrown at server/server.go:1519

				if t, ok := ar.c.Transport.(*http.Transport); ok {
					t.CloseIdleConnections()
					t.TLSClientConfig = opts.AccountResolverTLSConfig.Clone()
				}
			}
		}
		if len(opts.resolverPreloads) > 0 {
			// Lock ordering is account resolver -> server, so we need to release
			// the lock and reacquire it when done with account resolver's calls.
			ar := s.accResolver
			s.mu.Unlock()
			defer s.mu.Lock()
			if ar.IsReadOnly() {
				return fmt.Errorf("resolver preloads only available for writeable resolver types MEM/DIR/CACHE_DIR")
			}
			for k, v := range opts.resolverPreloads {
				_, err := jwt.DecodeAccountClaims(v)
				if err != nil {
					return fmt.Errorf("preload account error for %q: %v", k, err)
				}
				ar.Store(k, v)
			}
		}
	}
	return nil
}

// This will check preloads for validation issues.
func (s *Server) checkResolvePreloads() {
	opts := s.getOpts()
	// We can just check the read-only opts versions here, that way we do not need
	// to grab server lock or access s.accResolver.
	for k, v := range opts.resolverPreloads {
		claims, err := jwt.DecodeAccountClaims(v)
		if err != nil {
			s.Errorf("Preloaded account [%s] not valid", k)
			continue

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Regenerate/copy the account JWT: `nsc generate profile` or read the raw file under nsc's accounts dir and paste it fully
2. Validate out-of-band with `nsc accounts report` or `nats account info` before adding to config
3. Ensure correct JWT type: decode the first JSON payload segment and check `claims.nats.type == "account"`
4. Check YAML/JSON quoting so no characters are dropped or mangled

Example fix

// before
resolver_preload = { MYACC: "nsc describe -o me -a myacc output" }
// after
resolver_preload = { MYACC: "eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5In0.eyJ..." }

import "github.com/nats-io/jwt/v2"

func validatePreloads(preloads map[string]string) error {
    for k, v := range preloads {
        c, err := jwt.DecodeAccountClaims(v)
        if err != nil {
            return fmt.Errorf("preload %q is not a valid account JWT: %v", k, err)
        }
        _ = c
    }
    return nil
}

When it happens

Trigger: Calling ProcessOptions/Start with opts.resolverPreloads containing a value for which jwt.DecodeAccountClaims errors: value is empty, whitespace-wrapped, truncated, or not an account claims JWT (e.g. an operator JWT pasted by mistake).

Common situations: Pasting a JWT that lost characters through shell/editor mangling; storing the wrong JWT type (user or operator claims instead of account); YAML quoting stripping characters; using `nsc describe` output instead of the raw JWT file contents.

Related errors

• account jwt not found
• operators do not allow authorization callouts to be configur
• failed to create mapping transform for stream import subject
• store operation not supported for URL Resolver
• delete must be enabled in server config

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