What causes "addr (nats subject) must not be empty" in micro/go-micro?

Pass a valid NATS subject, e.g. transport.Listen("my.subject", ...)

addr (nats subject) must not be empty

Error message

addr (nats subject) must not be empty

What it means

Listen validates the NATS subject (addr) before creating the listener. If the address string is empty (and was not replaced by an auto-generated NATS inbox), Listen refuses to start since NATS cannot subscribe to a blank subject. Note that transport.DefaultAddress is pre-replaced with a random inbox, so the error only fires for explicitly empty addresses.

Source

Thrown at transport/nats/nats.go:484

	// secure might not be set
	if n.opts.TLSConfig != nil {
		opts.Secure = true
	}

	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 {

View on GitHub (pinned to 24529f1404)

Solutions

Pass a valid NATS subject, e.g. transport.Listen("my.subject", ...)
Use the DefaultAddress sentinel (""/0.0.0.0 style) so Listen generates a random inbox via nats.NewInbox()
Fix the configuration source (env var/flag) so the subject is populated before Listen

Example fix

// before
lis, err := t.Listen("")
// after
lis, err := t.Listen("micro.service.topic")
// or for a random inbox:
lis, err := t.Listen(server.DefaultAddress)

Defensive patterns

Strategy: validation

Validate before calling

func validateSubject(addr string) error {
	if addr == "" {
		return errors.New("nats subject must not be empty")
	}
	return nil
}
// if err := validateSubject(addr); err != nil { addr = server.DefaultAddress }

Prevention

Never pass empty strings as transport.Listen addresses; use server.DefaultAddress for a random inbox
Centralize subject constants instead of reading raw env values
Fail fast at config load if the address is empty

When it happens

Trigger: Calling transport.Listen(":", ... variants that resolve to "" ) — specifically passing addr == "" not equal to server.DefaultAddress, e.g. Listen("", ...) or an empty option value that bypasses the DefaultAddress substitution.

Common situations: Config file/env var for the service address left empty; template variable not expanded; passing DefaultAddress sentinel through a layer that already replaced it with ""; copy-paste removing the subject.

Related errors

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