addr (nats subject) must not contain space characters

Error message

addr (nats subject) must not contain space characters

What it means

NATS subjects are whitespace-delimited tokens in NATS's text protocol, so Listen rejects any addr containing a space. This prevents constructing an invalid subscription that the NATS server would refuse or misparse.

Source

Thrown at transport/nats/nats.go:490

	c, err := opts.Connect()
	if err != nil {
		return nil, err
	}

	// in case address has not been specifically set, create a new nats.Inbox()
	if addr == server.DefaultAddress {
		addr = nats.NewInbox()
	}

	// make sure addr subject is not empty
	if len(addr) == 0 {
		return nil, errors.New("addr (nats subject) must not be empty")
	}

	// since NATS implements a text based protocol, no space characters are
	// admitted in the addr (subject name)
	if strings.Contains(addr, " ") {
		return nil, errors.New("addr (nats subject) must not contain space characters")
	}

	return &ntportListener{
		addr: addr,
		conn: c,
		exit: make(chan bool, 1),
		so:   make(map[string]*ntportSocket),
		opts: n.opts,
	}, nil
}

func (n *ntport) Init(opts ...transport.Option) error {
	configure(n, opts...)
	return nil
}

func (n *ntport) Options() transport.Options {
	return n.opts

View on GitHub (pinned to 24529f1404)

Solutions

Replace spaces with valid subject tokens, e.g. "my.topic" (dots, letters, digits, -_ allowed)
Split multi-topic strings and create one listener per subject
strings.TrimSpace / normalize addresses loaded from env or config before Listen

Example fix

// before
lis, err := t.Listen("my service events")
// after
lis, err := t.Listen("my.service.events")

Defensive patterns

Strategy: validation

Validate before calling

func validSubject(addr string) bool {
	return addr != "" && !strings.Contains(addr, " ")
}
// if !validSubject(addr) { addr = strings.ReplaceAll(strings.TrimSpace(addr), " ", ".") }

Prevention

Normalize addresses with strings.TrimSpace and replace spaces with dots
Split comma/space-separated multi-topic strings into separate listeners
Use only [A-Za-z0-9._-] tokens for NATS subjects
Add a config-load validation step for all subject values

When it happens

Trigger: Calling transport.Listen(addr) where addr contains a space character, e.g. Listen("my topic") or an address built from a comma/space-joined list like "topic1, topic2".

Common situations: Human-readable topic names with spaces pasted into config; building a multi-subject string with ", " separators; trimming failures leaving leading/trailing spaces from env vars.

Related errors

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/6efaad8d18a295f6. Report an issue: GitHub.