hashicorp/nomad · error

must have at least client or server mode enabled

Error message

must have at least client or server mode enabled

What it means

NewAgent validates that the agent was constructed with at least one mode: client, server, or both. After enterprise setup, if both a.client and a.server are nil, no useful work can be done, so construction fails. This guards against an agent config that disables every role.

Source

Thrown at command/agent/agent.go:180

	// Global logger should match internal logger as much as possible
	golog.SetFlags(golog.LstdFlags | golog.Lmicroseconds)

	if err := a.setupConsuls(config.Consuls); err != nil {
		return nil, fmt.Errorf("Failed to initialize Consul client: %v", err)
	}

	if err := a.setupServer(); err != nil {
		return nil, err
	}
	if err := a.setupClient(); err != nil {
		return nil, err
	}

	if err := a.setupEnterpriseAgent(logger); err != nil {
		return nil, err
	}
	if a.client == nil && a.server == nil {
		return nil, fmt.Errorf("must have at least client or server mode enabled")
	}

	// If the agent is configured with TLS, set up the TLS metrics process to
	// emit certificate expiry metrics and start this.
	if !a.config.TLSConfig.IsEmpty() {
		tlsMetrics, err := newTLSMetrics(a.logger, a.config.TLSConfig, nil)
		if err != nil {
			return nil, fmt.Errorf("failed to set up TLS expiration metrics: %w", err)
		}
		a.tlsMetrics = tlsMetrics
		tlsMetrics.start(a.config.Telemetry.collectionInterval)
	}

	return a, nil
}

// convertServerConfig takes an agent config and log output and returns a Nomad
// Config. There may be missing fields that must be set by the agent. To do this

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set client { enabled = true } or server { enabled = true } in the agent config (or pass -client / -server flags).
2. Check that generated config (env vars, templates) actually enables one mode before startup.
3. If embedding NewAgent in Go, ensure Agent.config has ClientConfig or ServerConfig populated and enabled before calling NewAgent.

Example fix

// before (config.hcl)
client { enabled = false }
server { enabled = false }
// after
client { enabled = true }

// Go: before calling agent.NewAgent
cfg := &config.Agent{
    Client: clientCfg,
    Server: serverCfg,
}
if (clientCfg == nil || !clientCfg.Enabled) && (serverCfg == nil || !serverCfg.Enabled) {
    return fmt.Errorf("agent config must enable client or server mode")
}
a, err := agent.NewAgent(cfg, log)

func hasEnabledMode(cfg *config.Agent) bool {
    if cfg == nil { return false }
    c := cfg.Client != nil && cfg.Client.Enabled
    s := cfg.Server != nil && cfg.Server.Enabled
    return c || s
}

a, err := agent.NewAgent(cfg, logger)
if err != nil {
    if strings.Contains(err.Error(), "at least client or server mode") {
        logger.Error("no agent mode enabled; check client/server stanzas")
    }
    return err
}

When it happens

Trigger: Calling NewAgent (directly or via the `nomad agent` command via setupAgent/start) with a config where client.enabled=false and server.enabled=false, or where client/server setup silently skipped creation.

Common situations: Hand-edited config files setting both enabled = false; templates or env-based config generation accidentally omitting both stanzas; launching an agent binary without any role flags (e.g. missing -client/-server).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Failed to initialize Consul client: %v
• failed to set up TLS expiration metrics: %w
• server_join and start_join cannot both be defined; prefer se
• plugin not found
• wait config is nil or empty

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