hashicorp/nomad · error

reloading client config failed: %w

Error message

reloading client config failed: %w

What it means

Raised in handleReload (command/agent/command.go:1255) when the client-side portion of a SIGHUP reload fails: client.Reload(clientConfig) returns an error after the new client config was converted and finalized. The agent logs the error and wraps it so handleSignals reports 'reloading client config failed'; the agent continues running with its previous client configuration.

Source

Thrown at command/agent/command.go:1255

	}

	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 {
			c.agent.logger.Error("reloading client config failed", "error", err)
			return fmt.Errorf("reloading client config failed: %w", err)
		}
	}

	// reload HTTP server after we have reloaded both client and server, in case
	// we error in either of the above cases. For example, reloading the http
	// server to a TLS connection could succeed, while reloading the server's rpc
	// connections could fail.
	if shouldReloadHTTP {
		err := c.reloadHTTPServer()
		if err != nil {
			c.agent.httpLogger.Error("reloading config failed", "error", err)
		}
	}

	return nil
}

// checkNewConfigFiles is used to compare the previous and current config files

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the 'error' field in the agent log line 'reloading client config failed' for the concrete cause.
2. Fix the client stanza (validate datacenter, servers list, plugin dirs, TLS files) and re-send SIGHUP.
3. Verify the agent can reach the servers with the new settings (TLS handshake, gossip) before reloading.
4. If the changed field is not reloadable, restart the Nomad client agent with the new configuration.

Example fix

// before: client config with unreachable/mistyped servers
client { enabled = true; servers = ["10.0.0:4647"] } // missing host:port digits
// after
client {
  enabled    = true
  servers    = ["10.0.0.10:4647", "10.0.0.11:4647"]
  node_class = "compute"
}

// before SIGHUP, check client inputs:
for _, srv := range servers {
    if _, _, err := net.SplitHostPort(srv); err != nil {
        return fmt.Errorf("bad server address %q: %w", srv, err)
    }
}

if err := client.Reload(clientConfig); err != nil {
    logger.Error("reloading client config failed", "error", err)
    // retain previous client config; surface error to operator
    return fmt.Errorf("reloading client config failed: %w", err)
}

When it happens

Trigger: Sending SIGHUP after editing client-related config when client.Reload rejects it — e.g. invalid datacenter/region values, bad plugin or fingerprint configuration, unreachable servers in the new servers list, or failures re-registering the client with updated settings.

Common situations: Changing client stanza options that require re-registration (datacenter, node class) and hitting validation errors; pointing to servers over TLS with mismatched certs; malformed chroot/plugin paths in the client config; network issues preventing the client from rejoining the new server list.

Related errors

• reloading server config failed: %w
• Invalid agent policy: %#v
• client setup failed: %v
• cannot reload agent with nil configuration
• can't reload uninitialized RPC listener

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