{"record":{"id":"e9e8d2dc07617d5a","repo":"cloudflare/cloudflared","slug":"failed-to-create-lock-file-s","errorCode":null,"errorMessage":"failed to create lock file %s","messagePattern":"failed to create lock file (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"token/token.go","lineNumber":137,"sourceCode":"//  3. If the owner is alive, sleep for lockRetryInterval and retry.\n//  4. If the owner is dead (stale lock), remove the file and immediately\n//     retry the O_EXCL create. No sleep (the atomic create is the\n//     tiebreaker if multiple processes race to reclaim).\nfunc acquireLockFile(tokenPath string, log *zerolog.Logger) (*lockFile, error) {\n\tlockPath := tokenPath + \".lock\"\n\tdeadline := time.Now().Add(lockTimeout)\n\tlastURL := \"\"\n\tfor {\n\t\tif time.Now().After(deadline) {\n\t\t\treturn nil, fmt.Errorf(\"timed out waiting for lock file %s\", lockPath)\n\t\t}\n\t\tcontent, err := createLockFile(lockPath)\n\t\tif err == nil {\n\t\t\tlog.Debug().Str(\"path\", lockPath).Msg(\"lock file acquired\")\n\t\t\treturn &lockFile{path: lockPath, content: content, log: log}, nil\n\t\t}\n\t\tif !os.IsExist(err) {\n\t\t\treturn nil, errors.Wrapf(err, \"failed to create lock file %s\", lockPath)\n\t\t}\n\n\t\t// lock file exists, so check if the owner is still alive\n\t\tstale, content, checkErr := isLockFileStale(lockPath)\n\t\tif checkErr != nil {\n\t\t\t// file may be mid-write by another racer, or was removed\n\t\t\t// between our O_EXCL attempt and this read\n\t\t\tlog.Debug().Err(checkErr).Str(\"path\", lockPath).\n\t\t\t\tMsg(\"could not read lock file, retrying\")\n\t\t\ttime.Sleep(lockRetryInterval)\n\t\t\tcontinue\n\t\t}\n\n\t\tif !stale {\n\t\t\t// try to display the auth URL so the user can open a browser\n\t\t\t// manually if the original window is not visible\n\t\t\tif authURL := readAuthURL(tokenPath); authURL != \"\" && authURL != lastURL {\n\t\t\t\tfmt.Fprintf(os.Stderr, \"\\nAnother cloudflared process (pid %d) \"+","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/token/token.go#L119-L155","documentation":"This error comes from acquireLockFile when creating the cloudflared token lock file fails with an error other than 'already exists' — i.e. a real filesystem failure, not benign contention. The lock file (created with O_CREAT|O_EXCL semantics) prevents multiple cloudflared processes from racing to fetch the same token. Non-EEXIST failures are wrapped so the caller knows lock acquisition was impossible.","triggerScenarios":"getToken -> acquireLockFile where createLockFile fails for reasons other than os.IsExist: the token directory does not exist, the process lacks write permission on the directory (e.g. ~/.cloudflared owned by root), the disk is full, or the path is invalid/too long.","commonSituations":"Running cloudflared with a HOME it cannot write to; ~/.cloudflared created previously by a root-run instance so a non-root user cannot create files; read-only home volume or container filesystem; AppArmor/SELinux denying writes to the token directory.","solutions":["Ensure the token directory exists and is writable: mkdir -p ~/.cloudflared && chown -R $USER ~/.cloudflared","If cloudflared was ever run with sudo, fix ownership of files it created (sudo chown -R $USER ~/.cloudflared)","Check disk space (df -h) and filesystem mount state (read-only remount)","Read the wrapped underlying error to identify whether it is EACCES, ENOSPC, ENOENT, or EPERM and address accordingly"],"exampleFix":"// before: failing when the token directory is missing\nlock, err := acquireLockFile(appTokenPath, log)\n// after: ensure the directory exists before locking\nif err := os.MkdirAll(filepath.Dir(appTokenPath), 0700); err != nil {\n\treturn \"\", errors.Wrap(err, \"failed to create token directory\")\n}\nlock, err := acquireLockFile(appTokenPath, log)","handlingStrategy":"validation","validationCode":"// check the token directory is writable before running\nimport \"os\"\nif err := checkDirWritable(os.UserHomeDir + \"/.cloudflared\"); err != nil {\n\tlog.Fatal(err) // fix ownership/permissions first\n}","typeGuard":null,"tryCatchPattern":"lock, err := acquireLockFile(path, log)\nif err != nil && strings.Contains(err.Error(), \"failed to create lock file\") {\n\t// real FS failure (EACCES/ENOSPC): do NOT retry blindly; surface to operator\n\treturn fmt.Errorf(\"cannot lock token storage: %w — check ~/.cloudflared permissions\", err)\n}","preventionTips":["Never mix sudo and non-sudo cloudflared runs; chown ~/.cloudflared afterwards","Pre-create ~/.cloudflared with 0700 owned by the service user","Monitor disk space on hosts running cloudflared","Run cloudflared under a dedicated user with a stable HOME"],"tags":["filesystem","file-lock","permissions","token"],"backgroundTag":"file-write-failed","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}