hashicorp/nomad · error

can't reload uninitialized RPC listener

Error message

can't reload uninitialized RPC listener

What it means

Server.Reload calls reloadTLSConnections to hot-reload TLS settings. If the RPC listener or its cancellation context was never initialized (server not fully started, or startup failed partway), reload cannot proceed, so it logs a warning and returns this error. It is a defensive check against reloading a server that has no live RPC listener.

Source

Thrown at nomad/server.go:684

		return false
	}
	if parts[0] == "client" {
		// Clients may only connect to servers in their region
		return name == "client."+region+".nomad"
	}
	// Servers may connect to any Nomad RPC service for federation.
	return parts[0] == "server"
}

// reloadTLSConnections updates a server's TLS configuration and reloads RPC
// connections.
func (s *Server) reloadTLSConnections(newTLSConfig *config.TLSConfig) error {
	s.logger.Info("reloading server connections due to configuration changes")

	// Check if we can reload the RPC listener
	if s.rpcListener == nil || s.rpcCancel == nil {
		s.logger.Warn("unable to reload configuration due to uninitialized rpc listener")
		return fmt.Errorf("can't reload uninitialized RPC listener")
	}

	tlsConf, err := tlsutil.NewTLSConfiguration(newTLSConfig, true, true)
	if err != nil {
		s.logger.Error("unable to create TLS configuration", "error", err)
		return err
	}

	incomingTLS, tlsWrap, err := getTLSConf(newTLSConfig.EnableRPC, tlsConf, s.config.Region)
	if err != nil {
		s.logger.Error("unable to reset TLS context", "error", err)
		return err
	}

	// Store the new tls wrapper.
	s.tlsWrapLock.Lock()
	s.tlsWrap = tlsWrap
	s.tlsWrapLock.Unlock()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Restart the Nomad agent instead of reloading — the listener must be re-created from a clean start.
2. Check earlier logs for why the RPC listener failed to initialize (port bind failure, bad TLS config).
3. Free the RPC port (default 4647) or fix TLS cert paths, then start the agent fresh.
4. Only issue reload after the agent logs that it is fully started.

Example fix

// before
kill -HUP $(pidof nomad)   # while agent startup is failing/half-initialized
// after
systemctl restart nomad    # full restart after fixing the underlying listener/TLS problem

// before signaling reload, confirm the agent is fully started (RPC listener up)
// e.g. poll the agent HTTP API until /v1/agent/health?service=server returns 200

if err := srv.Reload(newCfg); err != nil && strings.Contains(err.Error(), "uninitialized RPC listener") {
    // don't retry reload; full restart required
    return restartAgent()
}

When it happens

Trigger: Sending SIGHUP or calling Server.Reload(newConfig) while the RPC listener failed to bind or the server never completed startup (s.rpcListener == nil or s.rpcCancel == nil).

Common situations: SIGHUP delivered during agent startup/crash recovery; port already bound so rpcListener setup failed earlier; operators running `nomad reload` against a half-started agent.

Related errors

• reloading server config failed: %w
• missing certificate information
• cannot reload agent with nil configuration
• reloading client config failed: %w
• no servers

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/02c621fc412ef5a5. Report an issue: GitHub.