hashicorp/nomad · error

start_join is not supported for Nomad clients

Error message

start_join is not supported for Nomad clients

What it means

start_join (and its server_join.start_join form) only makes sense for Nomad servers performing Raft bootstrap/manual joins. If a client stanza defines ServerJoin.StartJoin, Validate rejects the config because clients never start-join a cluster.

Source

Thrown at command/agent/retry_join.go:151

		}
		if config.Server.RetryMaxAttempts != 0 {
			return fmt.Errorf("server_join and retry_max cannot both be defined; prefer setting the server_join block")
		}

		if config.Server.RetryInterval != 0 {
			return fmt.Errorf("server_join and retry_interval cannot both be defined; prefer setting the server_join block")
		}

		if len(config.Server.ServerJoin.StartJoin) != 0 {
			return fmt.Errorf("retry_join and start_join cannot both be defined")
		}
	}

	// if retry_join is defined for the client, ensure that start_join is not
	// set as this configuration is only defined for servers.
	if config.Client != nil && config.Client.ServerJoin != nil {
		if config.Client.ServerJoin.StartJoin != nil {
			return fmt.Errorf("start_join is not supported for Nomad clients")
		}
	}

	return nil
}

// RetryJoin is used to handle retrying a join until it succeeds or all retries
// are exhausted.
func (r *retryJoiner) RetryJoin() {
	if len(r.joinCfg.RetryJoin) == 0 {
		return
	}

	attempt := 0

	addrsToJoin := strings.Join(r.joinCfg.RetryJoin, " ")
	r.logger.Info("starting retry join", "servers", addrsToJoin)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove client.server_join.start_join from the client config
2. Move start_join to the server stanza's server_join block where it is valid
3. For clients, only use client.server_join.retry_join / retry_max / retry_interval
4. Split shared and role-specific config files so server keys never leak into client configs

Example fix

// before
client {
  server_join {
    start_join = ["10.0.0.1"]
  }
}
// after
client {
  server_join {
    retry_join = ["10.0.0.1"]
  }
}

if c := cfg.Client; c != nil && c.ServerJoin != nil && c.ServerJoin.StartJoin != nil {
    return errors.New("start_join is invalid in the client stanza")
}

When it happens

Trigger: Config with client { server_join { start_join = [...] } } set to a non-nil value; retryJoiner.Validate fails at agent startup.

Common situations: Using one shared config file for both servers and clients and including server-only keys; copy-pasting a server config block into the client stanza.

Related errors

• Reschedule policy has unlimited attempts enabled and a low d
• Lock delay and TTL must be positive
• failed to initialize network configurator: %v
• missing task names
• https_handshake_timeout must be >= 0

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