What causes "client setup failed: %v" in hashicorp/nomad?

Read the wrapped '%v' detail in the log — it names the exact config field that failed

client setup failed: %v

Error message

client setup failed: %v

What it means

This error wraps any failure that occurs while building the Nomad client configuration during agent startup (a.clientConfig() in setupClient). setupClient is called by NewAgent, so any malformed client config stanza, unparsable field, or invalid option aborts agent bring-up. The wrapped error carries the underlying cause; this message only marks the phase.

Source

Thrown at command/agent/agent.go:1372

}

// setupClient is used to setup the client if enabled
func (a *Agent) setupClient() error {
	if !a.config.Client.Enabled {
		return nil
	}

	// Plugin setup must happen before the call to clientConfig, because it
	// copies the pointers to the plugin loaders from the Agent to the
	// Client config.
	if err := a.setupPlugins(); err != nil {
		return err
	}

	// Setup the configuration
	conf, err := a.clientConfig()
	if err != nil {
		return fmt.Errorf("client setup failed: %v", err)
	}

	// Reserve some ports for the plugins if we are on Windows
	if runtime.GOOS == "windows" {
		if err := a.reservePortsForClient(conf); err != nil {
			return err
		}
	}
	if conf.StateDBFactory == nil {
		conf.StateDBFactory = state.GetStateDBFactory(conf.DevMode)
	}

	// Set up a custom listener and dialer. This is used by Nomad clients when
	// running consul-template functions that utilize the Nomad API. We lazy
	// load this into the client config, therefore this needs to happen before
	// we call NewClient.
	a.builtinListener, a.builtinDialer = bufconndialer.New()
	conf.TemplateDialer = a.builtinDialer

View on GitHub (pinned to 482b49bf1a)

Solutions

Read the wrapped '%v' detail in the log — it names the exact config field that failed
Fix the offending entry in the [client] section of the agent config file (or the -client-* CLI flags)
Run `nomad agent -config ... -verify-only` or `nomad config validate` to check the config before starting
Upgrade/downgrade Nomad so config keys match the running binary version

Example fix

// before (invalid client option)
client {
  option = "bogus-value"
}
// after
client {
  enabled = true
  servers = ["127.0.0.1:4647"]
}

Defensive patterns

Strategy: validation

Validate before calling

if err := exec.Command("nomad", "config", "validate", cfgPath).Run(); err != nil {
    return fmt.Errorf("invalid agent config %s: %w", cfgPath, err)
}

Try / catch

if err := NewAgent(...); err != nil {
    var cfgErr *ConfigParseError
    if strings.Contains(err.Error(), "client setup failed") {
        log.Fatalf("fix [client] config: %v", err)
    }
    return err
}

Prevention

Run `nomad config validate` in CI before deploys
Pin client config keys to the Nomad version's documented schema
Test agent startup with -verify-only in staging

When it happens

Trigger: Calling NewAgent (e.g. `nomad agent -client`) where a.clientConfig() returns an error: invalid or unparsable [client] config block, bad datacenter/name values, invalid client options (e.g. bad max_kill_timeout, unknown option keys), or bad addresses/interfaces in the config.

Common situations: Typo or invalid type in the client stanza of an HCL/JSON config file; environment-derived config overrides producing invalid values; upgrading Nomad after a client option was removed or renamed so the old config no longer validates.

Related errors

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