{"record":{"id":"bb07dcae5475b75f","repo":"hashicorp/nomad","slug":"retry-join-and-start-join-cannot-both-be-defined","errorCode":null,"errorMessage":"retry_join and start_join cannot both be defined","messagePattern":"retry_join and start_join cannot both be defined","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/retry_join.go","lineNumber":143,"sourceCode":"\t// If retry_join is defined for the server, ensure that deprecated\n\t// fields and the server_join block are not both set\n\tif config.Server != nil && config.Server.ServerJoin != nil && len(config.Server.ServerJoin.RetryJoin) != 0 {\n\t\tif len(config.Server.RetryJoin) != 0 {\n\t\t\treturn fmt.Errorf(\"server_join and retry_join cannot both be defined; prefer setting the server_join block\")\n\t\t}\n\t\tif len(config.Server.StartJoin) != 0 {\n\t\t\treturn fmt.Errorf(\"server_join and start_join cannot both be defined; prefer setting the server_join block\")\n\t\t}\n\t\tif config.Server.RetryMaxAttempts != 0 {\n\t\t\treturn fmt.Errorf(\"server_join and retry_max cannot both be defined; prefer setting the server_join block\")\n\t\t}\n\n\t\tif config.Server.RetryInterval != 0 {\n\t\t\treturn fmt.Errorf(\"server_join and retry_interval cannot both be defined; prefer setting the server_join block\")\n\t\t}\n\n\t\tif len(config.Server.ServerJoin.StartJoin) != 0 {\n\t\t\treturn fmt.Errorf(\"retry_join and start_join cannot both be defined\")\n\t\t}\n\t}\n\n\t// if retry_join is defined for the client, ensure that start_join is not\n\t// set as this configuration is only defined for servers.\n\tif config.Client != nil && config.Client.ServerJoin != nil {\n\t\tif config.Client.ServerJoin.StartJoin != nil {\n\t\t\treturn fmt.Errorf(\"start_join is not supported for Nomad clients\")\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// RetryJoin is used to handle retrying a join until it succeeds or all retries\n// are exhausted.\nfunc (r *retryJoiner) RetryJoin() {\n\tif len(r.joinCfg.RetryJoin) == 0 {","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/retry_join.go#L125-L161","documentation":"When the deprecated top-level server retry_join is defined, retryJoiner.Validate also ensures server_join.start_join is not simultaneously set — automatic retry joining and manual one-shot start joining are mutually exclusive in the same stanza.","triggerScenarios":"Config where server.retry_join (or server_join.retry_join) is non-empty AND server.server_join.start_join is non-empty; Validate fails during startup.","commonSituations":"Operators combining a static bootstrap list (start_join) with dynamic cloud auto-join (retry_join) without realizing they conflict; merging config fragments from different environments.","solutions":["Pick one join strategy: remove server_join.start_join to use retry_join, or remove retry_join entries to use start_join","Keep the server_join block as the single place configuring join behavior","Validate the final config with nomad config validate"],"exampleFix":"// before\nserver {\n  retry_join = [\"10.0.0.1\"]\n  server_join {\n    start_join = [\"10.0.0.2\"]\n  }\n}\n// after\nserver {\n  server_join {\n    retry_join = [\"10.0.0.1\"]\n  }\n}","handlingStrategy":"validation","validationCode":"if s := cfg.Server; s != nil && (len(s.RetryJoin) > 0 || (s.ServerJoin != nil && len(s.ServerJoin.RetryJoin) > 0)) && s.ServerJoin != nil && len(s.ServerJoin.StartJoin) > 0 {\n    return errors.New(\"retry_join and start_join are mutually exclusive\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Choose one join mechanism per stanza: retry_join (automatic) or start_join (manual bootstrap)","Keep all join settings inside the server_join block","Validate merged config fragments from multiple environments","Run nomad config validate before deploys"],"tags":["nomad","configuration","validation"],"backgroundTag":"config-conflict","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"}