{"record":{"id":"02c621fc412ef5a5","repo":"hashicorp/nomad","slug":"can-t-reload-uninitialized-rpc-listener","errorCode":null,"errorMessage":"can't reload uninitialized RPC listener","messagePattern":"can't reload uninitialized RPC listener","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/server.go","lineNumber":684,"sourceCode":"\t\treturn false\n\t}\n\tif parts[0] == \"client\" {\n\t\t// Clients may only connect to servers in their region\n\t\treturn name == \"client.\"+region+\".nomad\"\n\t}\n\t// Servers may connect to any Nomad RPC service for federation.\n\treturn parts[0] == \"server\"\n}\n\n// reloadTLSConnections updates a server's TLS configuration and reloads RPC\n// connections.\nfunc (s *Server) reloadTLSConnections(newTLSConfig *config.TLSConfig) error {\n\ts.logger.Info(\"reloading server connections due to configuration changes\")\n\n\t// Check if we can reload the RPC listener\n\tif s.rpcListener == nil || s.rpcCancel == nil {\n\t\ts.logger.Warn(\"unable to reload configuration due to uninitialized rpc listener\")\n\t\treturn fmt.Errorf(\"can't reload uninitialized RPC listener\")\n\t}\n\n\ttlsConf, err := tlsutil.NewTLSConfiguration(newTLSConfig, true, true)\n\tif err != nil {\n\t\ts.logger.Error(\"unable to create TLS configuration\", \"error\", err)\n\t\treturn err\n\t}\n\n\tincomingTLS, tlsWrap, err := getTLSConf(newTLSConfig.EnableRPC, tlsConf, s.config.Region)\n\tif err != nil {\n\t\ts.logger.Error(\"unable to reset TLS context\", \"error\", err)\n\t\treturn err\n\t}\n\n\t// Store the new tls wrapper.\n\ts.tlsWrapLock.Lock()\n\ts.tlsWrap = tlsWrap\n\ts.tlsWrapLock.Unlock()","sourceCodeStart":666,"sourceCodeEnd":702,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L666-L702","documentation":"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.","triggerScenarios":"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).","commonSituations":"SIGHUP delivered during agent startup/crash recovery; port already bound so rpcListener setup failed earlier; operators running `nomad reload` against a half-started agent.","solutions":["Restart the Nomad agent instead of reloading — the listener must be re-created from a clean start.","Check earlier logs for why the RPC listener failed to initialize (port bind failure, bad TLS config).","Free the RPC port (default 4647) or fix TLS cert paths, then start the agent fresh.","Only issue reload after the agent logs that it is fully started."],"exampleFix":"// before\nkill -HUP $(pidof nomad)   # while agent startup is failing/half-initialized\n// after\nsystemctl restart nomad    # full restart after fixing the underlying listener/TLS problem","handlingStrategy":"retry","validationCode":"// before signaling reload, confirm the agent is fully started (RPC listener up)\n// e.g. poll the agent HTTP API until /v1/agent/health?service=server returns 200","typeGuard":null,"tryCatchPattern":"if err := srv.Reload(newCfg); err != nil && strings.Contains(err.Error(), \"uninitialized RPC listener\") {\n    // don't retry reload; full restart required\n    return restartAgent()\n}","preventionTips":["Only send SIGHUP after the agent logs successful startup.","Fix RPC port conflicts and TLS paths so the listener binds on first start.","Use systemd unit health checks before reload automation."],"tags":["tls","reload","rpc","sighup"],"backgroundTag":"uninitialized-rpc-listener","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}