{"record":{"id":"018c502159df8203","repo":"hashicorp/nomad","slug":"node-id-setup-failed-v","errorCode":null,"errorMessage":"node ID setup failed: %v","messagePattern":"node ID setup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/client.go","lineNumber":1616,"sourceCode":"\treturn id, secret, nil\n}\n\n// setupNode is used to setup the initial node\nfunc (c *Client) setupNode() error {\n\tc.configLock.Lock()\n\tdefer c.configLock.Unlock()\n\n\tnewConfig := c.config.Copy()\n\tnode := newConfig.Node\n\tif node == nil {\n\t\tnode = &structs.Node{}\n\t\tnewConfig.Node = node\n\t}\n\n\t// Generate an ID and secret for the node\n\tid, secretID, err := ensureNodeID(newConfig)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"node ID setup failed: %v\", err)\n\t}\n\n\tnode.ID = id\n\tnode.SecretID = secretID\n\tif node.Attributes == nil {\n\t\tnode.Attributes = make(map[string]string)\n\t}\n\tif node.Links == nil {\n\t\tnode.Links = make(map[string]string)\n\t}\n\tif node.Drivers == nil {\n\t\tnode.Drivers = make(map[string]*structs.DriverInfo)\n\t}\n\tif node.CSIControllerPlugins == nil {\n\t\tnode.CSIControllerPlugins = make(map[string]*structs.CSIInfo)\n\t}\n\tif node.CSINodePlugins == nil {\n\t\tnode.CSINodePlugins = make(map[string]*structs.CSIInfo)","sourceCodeStart":1598,"sourceCodeEnd":1634,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L1598-L1634","documentation":"Nomad's client wraps any failure from ensureNodeID, which generates or restores the node's ID and secret ID (typically via the state DB or server registration), with this message. Without a node ID the client cannot register or heartbeat with the servers, so setup aborts. The wrapped %v carries the underlying cause (state DB failure, RPC error, etc.).","triggerScenarios":"ensureNodeID returns an error: the local state DB cannot read/write the stored node identity, or generating/renewing the node secret fails during client setup (client.NewClient / node setup path).","commonSituations":"Corrupt or unwritable Nomad data_dir; stale identity rows in the boltdb state store; server unreachable during initial ID provisioning; permissions issues on the data directory after running as a different user.","solutions":["Check the wrapped inner error message to identify whether it is a state DB or RPC failure","Verify the Nomad data_dir exists, is writable by the Nomad user, and has correct permissions","Stop the agent, back up, and remove/repair the client state DB (state.db) so the ID can be regenerated","Ensure servers are reachable (retry_join/consul discovery) if ID provisioning requires RPC"],"exampleFix":"// before\nnode {\n  # no explicit id, relying on corrupt state.db\n}\n// after\n# stop nomad, fix permissions, or set a stable ID\nnode {\n  id = \"fixed-node-id\"\n}","handlingStrategy":"validation","validationCode":"// before starting the client\nif err := ensureDataDirWritable(cfg.DataDir); err != nil {\n\treturn fmt.Errorf(\"data_dir not writable, node ID setup will fail: %w\", err)\n}\nif cfg.NodeID == \"\" {\n\t// ensure state.db is intact or pin a stable node.id\n}","typeGuard":null,"tryCatchPattern":"id, secretID, err := ensureNodeID(cfg)\nif err != nil {\n\tlogger.Error(\"node ID setup failed\", \"err\", err)\n\treturn retry.WithBackoff(func() error { return ensureNodeID(cfg) })\n}","preventionTips":["Pin a stable node.id in config to survive state.db loss","Monitor data_dir free space and permissions with config management","Never share one data_dir between multiple agents","Back up state.db before Nomad upgrades"],"tags":["nomad-client","node-registration","state-db"],"backgroundTag":"node-registration-failed","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"}