{"record":{"id":"1c2c2fb2171ddba4","repo":"hashicorp/nomad","slug":"failed-creating-state-dir-s","errorCode":null,"errorMessage":"failed creating state dir: %s","messagePattern":"failed creating state dir: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":687,"sourceCode":"\tc.shutdownGroup.Go(c.emitStats)\n\n\tc.logger.Info(\"started client\", \"node_id\", c.NodeID())\n\treturn c, nil\n}\n\n// Ready returns a chan that is closed when the client is fully initialized\nfunc (c *Client) Ready() <-chan struct{} {\n\treturn c.serversContactedCh\n}\n\n// init is used to initialize the client and perform any setup\n// needed before we begin starting its various components.\nfunc (c *Client) init() error {\n\t// Ensure the state dir exists if we have one\n\tconf := c.GetConfig()\n\tif conf.StateDir != \"\" {\n\t\tif err := os.MkdirAll(conf.StateDir, 0700); err != nil {\n\t\t\treturn fmt.Errorf(\"failed creating state dir: %s\", err)\n\t\t}\n\n\t} else {\n\t\t// Otherwise make a temp directory to use.\n\t\tp, err := os.MkdirTemp(\"\", \"NomadClient\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed creating temporary directory for the StateDir: %v\", err)\n\t\t}\n\n\t\tp, err = filepath.EvalSymlinks(p)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to find temporary directory for the StateDir: %v\", err)\n\t\t}\n\n\t\tconf = c.UpdateConfig(func(c *config.Config) {\n\t\t\tc.StateDir = p\n\t\t})\n\t}","sourceCodeStart":669,"sourceCodeEnd":705,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L669-L705","documentation":"Client.init() ensures the configured state directory exists using os.MkdirAll with mode 0700. If MkdirAll fails (a parent component of the path is not a directory, permissions, read-only fs), init returns this error, which NewClient surfaces wrapped as \"failed to initialize client\".","triggerScenarios":"client { state_dir = \"...\" } set to a path whose creation fails: a path component is an existing regular file, the parent dir is not writable by the nomad user, or the mount is read-only.","commonSituations":"Typo'd state_dir pointing into a file (e.g. state_dir = \"/etc/nomad.conf\"); data volume mounted read-only after maintenance; running the agent as a non-root user without write access to the configured path.","solutions":["Check the wrapped inner OS error: \"not a directory\" means a path component is a file; \"permission denied\" means fix ownership.","Ensure the nomad user owns or can write to state_dir: mkdir -p && chown nomad:nomad.","Verify the volume backing state_dir is mounted read-write.","If state_dir was intentionally unset, confirm config parsing actually left it empty (then Nomad creates a temp dir instead)."],"exampleFix":"// before\nclient { state_dir = \"/etc/nomad.d/state\" }  # /etc/nomad.d is root-only\n// after\nsudo mkdir -p /opt/nomad/state && sudo chown nomad:nomad /opt/nomad/state\nclient { state_dir = \"/opt/nomad/state\" }","handlingStrategy":"validation","validationCode":"// precheck the configured state dir before launching the agent\nfunc ensureStateDir(path string) error {\n    if fi, err := os.Stat(path); err == nil && !fi.IsDir() {\n        return fmt.Errorf(\"%s is a file, not a directory\", path)\n    }\n    if err := os.MkdirAll(path, 0o700); err != nil {\n        return fmt.Errorf(\"cannot create state dir %s: %w\", path, err)\n    }\n    probe := filepath.Join(path, \".probe\")\n    if err := os.WriteFile(probe, nil, 0o600); err != nil { return err }\n    return os.Remove(probe)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run this precheck in systemd ExecStartPre or init scripts before the agent starts","Mount data volumes read-write and verify after maintenance/reboots","chown the state dir to the nomad service user at provisioning time","Avoid nested paths where an intermediate component might be a file"],"tags":["filesystem","state-dir","initialization"],"backgroundTag":"directory-creation-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"}