{"record":{"id":"0cf87919d5cd8c9e","repo":"hashicorp/nomad","slug":"server-join-and-start-join-cannot-both-be-defined","errorCode":null,"errorMessage":"server_join and start_join cannot both be defined; prefer setting the server_join block","messagePattern":"server_join and start_join cannot both be defined; prefer setting the server_join block","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/command.go","lineNumber":1434,"sourceCode":"\t}\n\n\treturn inm, nil\n}\n\nfunc (c *Command) startupJoin(config *Config) error {\n\t// Nothing to do\n\tif !config.Server.Enabled {\n\t\treturn nil\n\t}\n\n\t// Validate both old and new aren't being set\n\told := len(config.Server.StartJoin)\n\tvar new int\n\tif config.Server.ServerJoin != nil {\n\t\tnew = len(config.Server.ServerJoin.StartJoin)\n\t}\n\tif old != 0 && new != 0 {\n\t\treturn fmt.Errorf(\"server_join and start_join cannot both be defined; prefer setting the server_join block\")\n\t}\n\n\t// Nothing to do\n\tif old+new == 0 {\n\t\treturn nil\n\t}\n\n\t// Combine the lists and join\n\tjoining := config.Server.StartJoin\n\tif new != 0 {\n\t\tjoining = append(joining, config.Server.ServerJoin.StartJoin...)\n\t}\n\n\tc.Ui.Output(\"Joining cluster...\")\n\tn, err := c.agent.server.Join(joining)\n\tif err != nil {\n\t\treturn err\n\t}","sourceCodeStart":1416,"sourceCodeEnd":1452,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/command.go#L1416-L1452","documentation":"Nomad agents act as Consul servers; startup join can be configured either via the legacy top-level `start_join` list or the newer `server_join` block. This error is thrown during agent startup when both are set, because merging them would be ambiguous.","triggerScenarios":"Server config defines non-empty `server.start_join` AND a non-nil `server.server_join` block with non-empty `server_join.start_join`. Detected in startupJoin at agent startup (called from Run).","commonSituations":"Migrating config to the newer `server_join` block but forgetting to delete the old `start_join` key; merging agent config files or base/hcl overlays that each define one of the two; copy-pasting example configs from different Nomad versions.","solutions":["Remove the legacy `start_join` list from the server config and keep only the `server_join` block (preferred).","Or, if staying on legacy config, remove the `server_join` block so only `start_join` remains.","Search all config files passed via -config (including directories) for duplicates of the two keys."],"exampleFix":"// before\nserver {\n  start_join = [\"10.0.0.5\", \"10.0.0.6\"]\n  server_join { start_join = [\"10.0.0.5\"] }\n}\n// after\nserver {\n  server_join { start_join = [\"10.0.0.5\", \"10.0.0.6\"] }\n}","handlingStrategy":"validation","validationCode":"func validateServerJoin(cfg *ServerConfig) error {\n  if len(cfg.StartJoin) > 0 && cfg.ServerJoin != nil && len(cfg.ServerJoin.StartJoin) > 0 {\n    return errors.New(\"only one of start_join or server_join.start_join may be set\")\n  }\n  return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer the server_join block in all new configs","Grep config templates for start_join when upgrading Nomad","Validate agent config in CI with `nomad agent -config ... -verify-only`"],"tags":["config","nomad","consul","startup"],"backgroundTag":"conflicting-config-options","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}