{"record":{"id":"82700dd9c673aa4a","repo":"hashicorp/nomad","slug":"failed-to-find-temporary-directory-for-the-statedi","errorCode":null,"errorMessage":"failed to find temporary directory for the StateDir: %v","messagePattern":"failed to find temporary directory for the StateDir: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/client.go","lineNumber":699,"sourceCode":"// 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}\n\tc.logger.Info(\"using state directory\", \"state_dir\", conf.StateDir)\n\n\t// Open the state database\n\tdb, err := conf.StateDBFactory(c.logger, conf.StateDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to open state database: %v\", err)\n\t}\n\n\t// Upgrade the state database\n\tif err := db.Upgrade(); err != nil {\n\t\t// Upgrade only returns an error on critical persistence\n\t\t// failures in which an operator should intervene before the","sourceCodeStart":681,"sourceCodeEnd":717,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L681-L717","documentation":"During Nomad client initialization, when no explicit StateDir is configured, the client creates a temporary directory for state and then calls filepath.EvalSymlinks on it. If EvalSymlinks fails, the resolved path cannot be determined and init aborts with this error wrapping the OS error. It indicates the freshly created temp directory is not accessible via path resolution.","triggerScenarios":"NewClient/TestClient_Init/TestRPCOnlyClient init path with conf.StateDir empty: os.MkdirTemp succeeds but filepath.EvalSymlinks(p) returns an error immediately after creation.","commonSituations":"Hosts with broken TMPDIR settings pointing to non-existent or inaccessible directories, container images with missing/incorrect temp volume mounts, or heavily sandboxed environments where symlink resolution fails due to permissions or race conditions.","solutions":["Check that the effective temp directory (TMPDIR or /tmp) exists, is writable, and has no broken symlink components.","Set an explicit state_dir in the client config so the temp-dir creation path is skipped entirely.","Inspect the wrapped %v OS error for the exact syscall failure (e.g. ENOENT, EACCES) and fix the filesystem/permissions accordingly."],"exampleFix":"// before (broken TMPDIR)\nenv TMPDIR=/nonexistent nomad agent -client\n// after\nmkdir -p /var/lib/nomad/state\n# config.hcl\nclient {\n  state_dir = \"/var/lib/nomad/state\"\n}","handlingStrategy":"validation","validationCode":"tmp := os.TempDir()\nif fi, err := os.Stat(tmp); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"temp dir %q unusable: %v\", tmp, err)\n}","typeGuard":null,"tryCatchPattern":"if err := clientInit(); err != nil {\n    if strings.Contains(err.Error(), \"failed to find temporary directory for the StateDir\") {\n        // inspect wrapped OS error, fix TMPDIR, retry with explicit state_dir\n    }\n}","preventionTips":["Set an explicit state_dir in client config to avoid temp-dir resolution","Verify TMPDIR points to a real writable directory before starting the agent","Avoid symlinked or overlay temp locations on production nodes"],"tags":["client-init","filesystem","temp-directory"],"backgroundTag":"temp-dir-resolution-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"}