hashicorp/nomad · error

reloading server config failed: %w

Error message

reloading server config failed: %w

What it means

Raised in handleReload (command/agent/command.go:1235) when, during a SIGHUP-triggered reload, the rebuilt server configuration fails to apply via server.Reload(sconf). The agent logs the error and returns a wrapped error so handleSignals can report that reloading the server config failed; the agent keeps running with the old server configuration.

Source

Thrown at command/agent/command.go:1235

			return nil
		}
	}

	if s := c.agent.Server(); s != nil {
		c.agent.logger.Debug("starting reload of server config")
		sconf, err := convertServerConfig(newConf)
		if err != nil {
			c.agent.logger.Error("failed to convert server config", "error", err)
			return nil
		}

		// Finalize the config to get the agent objects injected in
		c.agent.finalizeServerConfig(sconf)

		// Reload the config
		if err := s.Reload(sconf); err != nil {
			c.agent.logger.Error("reloading server config failed", "error", err)
			return fmt.Errorf("reloading server config failed: %w", err)
		}
	}

	if client := c.agent.Client(); client != nil {
		c.agent.logger.Debug("starting reload of client config")
		clientConfig, err := convertClientConfig(newConf)
		if err != nil {
			c.agent.logger.Error("failed to convert client config", "error", err)
			return nil
		}

		// Finalize the config to get the agent objects injected in
		if err := c.agent.finalizeClientConfig(clientConfig); err != nil {
			c.agent.logger.Error("failed to finalize client config", "error", err)
			return nil
		}

		if err := client.Reload(clientConfig); err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the 'error' detail in the agent log line 'reloading server config failed' to identify the exact failing setting.
2. Validate the new config (cert/key files exist, paths correct, values allowed for reload) and re-send SIGHUP after fixing.
3. If the changed setting is not reloadable (e.g. certain raft/serf fields), restart the agent with the new config instead of relying on SIGHUP.
4. Roll back to the previous known-good config file and reload to restore operation, then apply changes incrementally.

Example fix

// before: reloading with an invalid cert path
server { enabled = true; tls_http = 1 } // typo'd value fails on reload
// after: valid, reloadable settings
tls {
  http = true
  rpc  = true
  ca_file   = "/etc/nomad.d/tls/ca.pem"
  cert_file = "/etc/nomad.d/tls/server.pem"
  key_file  = "/etc/nomad.d/tls/server-key.pem"
}

// before SIGHUP, validate server config inputs:
for _, f := range []string{caFile, certFile, keyFile} {
    if _, err := os.Stat(f); err != nil {
        return fmt.Errorf("missing TLS file %s: %w", f, err)
    }
}

// agent-side pattern mirrored in callers/handlers:
if err := server.Reload(sconf); err != nil {
    logger.Error("reloading server config failed", "error", err)
    // keep old config active; alert and require operator fix before next SIGHUP
    return fmt.Errorf("reloading server config failed: %w", err)
}

When it happens

Trigger: Sending SIGHUP to the Nomad agent after editing server-related config when server.Reload rejects the new config — e.g. invalid TLS certificate/key paths or unparseable certs, changing fields that are not reloadable, or an RPC mux/raft reload failure with the new settings.

Common situations: Rotating TLS certificates with a wrong path or mismatched key; pointing servers at a new gossip/serf key that is invalid; attempting to change immutable server settings via reload instead of a restart; typo'd server stanza values that only fail at reload time.

Related errors

• reloading client config failed: %w
• cannot reload agent with nil configuration
• can't reload uninitialized RPC listener
• tls_server_name may only be set for Consul service checks
• Invalid agent policy: %#v

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