{"record":{"id":"39d97615cd97ef8b","repo":"nats-io/nats-server","slug":"gsl-invalid-subject","errorCode":null,"errorMessage":"gsl: invalid subject","messagePattern":"gsl: invalid subject","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/gsl/gsl.go","lineNumber":40,"sourceCode":"// Sublist is a routing mechanism to handle subject distribution and\n// provides a facility to match subjects from published messages to\n// interested subscribers. Subscribers can have wildcard subjects to\n// match multiple published subjects.\n\n// Common byte variables for wildcards and token separator.\nconst (\n\tpwc     = '*'\n\tpwcs    = \"*\"\n\tfwc     = '>'\n\tfwcs    = \">\"\n\ttsep    = \".\"\n\tbtsep   = '.'\n\t_EMPTY_ = \"\"\n)\n\n// Sublist related errors\nvar (\n\tErrInvalidSubject    = errors.New(\"gsl: invalid subject\")\n\tErrNotFound          = errors.New(\"gsl: no matches found\")\n\tErrNilChan           = errors.New(\"gsl: nil channel\")\n\tErrAlreadyRegistered = errors.New(\"gsl: notification already registered\")\n)\n\n// SimpleSublist is an alias type for GenericSublist that takes\n// empty values, useful for tracking interest only without any\n// unnecessary allocations.\ntype SimpleSublist = GenericSublist[struct{}]\n\n// NewSimpleSublist will create a simple sublist.\nfunc NewSimpleSublist() *SimpleSublist {\n\treturn &GenericSublist[struct{}]{root: newLevel[struct{}]()}\n}\n\n// A GenericSublist stores and efficiently retrieves subscriptions.\ntype GenericSublist[T comparable] struct {\n\tsync.RWMutex","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/gsl/gsl.go#L22-L58","documentation":"ErrInvalidSubject ('gsl: invalid subject') is the generic sublist error returned when a subject string is not a valid NATS subject. In server/accounts.go it is returned when validating account-scoped subjects (token position checks) and when validating subject-mapping from/to subjects with IsValidSubject. It is the shared sentinel for all 'this subject string is malformed' cases in the sublist packages.","triggerScenarios":"Inserting/subscribing with a subject containing empty tokens ('foo..bar'), illegal characters, a leading/trailing dot, or failing account-position wildcard checks (token[accountPos-1] != \"*\"); mapping validation where !IsValidSubject(from) || !IsValidSubject(to) (server/accounts.go:1676).","commonSituations":"Config files with malformed subjects (double dots, spaces, wrong wildcard placement), code building subjects with string concatenation producing empty tokens, account bindings where the wildcard is not at the required token position.","solutions":["Print/inspect the offending subject and fix its syntax: no empty tokens, valid characters, wildcards (*) only as full tokens.","For account-position validation, ensure the token at the expected account position is exactly \"*\" or supply enough tokens (len(token) >= accountPos).","Validate subjects programmatically with server.IsValidSubject before inserting/registration."],"exampleFix":"// before\nsub, _ := subject  // e.g. \"foo..bar\" from joining\nsub := strings.Join(parts, \".\")\n// after\nif !IsValidSubject(sub) {\n    return fmt.Errorf(\"bad subject %q\", sub)\n}","handlingStrategy":"validation","validationCode":"if !gsl.IsValidSubject(subject) {\n    return fmt.Errorf(\"invalid subject %q\", subject)\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, gsl.ErrInvalidSubject) {\n    return fmt.Errorf(\"bad subject syntax: %w\", err)\n}","preventionTips":["Validate subjects with IsValidSubject before insert/subscribe.","Avoid manual string concatenation of subject tokens; join non-empty tokens only.","Check wildcard placement rules (\"*\" and \">\" only as full tokens, at correct positions)."],"tags":["nats","subject","validation","sublist"],"backgroundTag":"invalid-subject","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}