nats-io/nats-server · error

remote %s: cannot be added at the moment, try again

Error message

remote %s: cannot be added at the moment, try again

What it means

When a reload adds new leaf remotes, NATS checks whether the same remote name is still registered with a connection in progress in s.rmLeafRemoteCfgs. If so, after exhausting retries the reload fails with 'cannot be added at the moment, try again'.

Source

Thrown at server/reload.go:1040

				compressionChanged: !lrc.Compression.equals(&rlo.Compression),
				disabledChanged:    disabledChanged,
				opts:               rlo,
			}
			lrc.RUnlock()
			nlo.changed[lrc] = lnro
		}
		if len(nlo.added) > 0 {
			// Go through the added list and check if an added was recently removed and,
			// if that is the case, is it still in the `s.rmLeafRemoteCfgs` map, which
			// may mean that there was a connect-in-progress that did not complete yet.
			// Either try again (if it is the first failure) or return an error.
			for _, rlo := range nlo.added {
				if _, cip := s.rmLeafRemoteCfgs[rlo.name()]; cip {
					s.mu.RUnlock()
					if failed < maxAttempts-1 {
						continue forLoop
					}
					return nil, fmt.Errorf(remoteErrFormat, rlo.safeName(),
						"cannot be added at the moment, try again")
				}
			}
		}
		s.mu.RUnlock()
		break
	}

	// Now we want to make sure that there were actual changes, so that we don't
	// cause a reload of leafnodes for nothing. However, if one has (or all have)
	// been removed we still need to invoke leafNodeOption.Apply().
	if !nlo.tlsFirstChanged && !nlo.compressionChanged && !removed && len(nlo.added) == 0 && len(nlo.changed) == 0 {
		return nil, nil
	}

	return nlo, nil
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Retry the reload after the previous remote connection finishes closing.
2. Give the new remote a distinct name in leafnodes config to avoid the collision.
3. Restart the server if the add must take effect immediately and the old connection is stuck.

Example fix

// before
leafnodes { remotes: [ { name: "r1", url: "nats://new:4222" } ] } // old r1 still connecting
// after
leafnodes { remotes: [ { name: "r2", url: "nats://new:4222" } ] } // or reload later

// avoid reusing a name still disconnecting: use unique remote names
if nameInUseDuringReload(newRemote.Name) {
    return fmt.Errorf("choose a new name for remote %q", newRemote.Name)
}

for attempt := 0; attempt < 3; attempt++ {
    err := srv.Reload()
    if err == nil || !strings.Contains(err.Error(), "cannot be added at the moment") {
        break
    }
    time.Sleep(2 * time.Second)
}

When it happens

Trigger: Adding a new leafnodes.remotes[] entry whose name collides with an existing remote being disconnected/reconnected (connection-in-progress flag set) during reload.

Common situations: Rapid config reloads where a remote was just removed and re-added; renaming URLs while keeping the same remote name on a busy connection.

Related errors

• field "Users": old=%v, new=%v
• remote %s: %s
• could not look up or create the retained messages stream for
• OnReload, sort or explicitly skip type: %s
• unable to add account %q to the list of dedicated routes: %v

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