cloudflare/cloudflared · error

timed out waiting for lock file %s

Error message

timed out waiting for lock file %s

What it means

Lock-contention failure in acquireLockFile: another cloudflared process holds the token lock file (tokenPath + '.lock') with a live PID and matching start time, and the loop never acquired the lock before its deadline expired. Prevents two processes from mutating the same access-token file concurrently.

Source

Thrown at token/token.go:129

// acquireLockFile loops until it successfully creates a lock file for the
// given token file path. The lock file is created at tokenPath + ".lock".
//
// On each iteration:
//  1. Try to create the file atomically with O_CREATE|O_EXCL.
//     If that succeeds, write our PID + start time and return the lock.
//  2. If the file already exists, read it and check whether the owning
//     process is still alive (PID exists and start time matches).
//  3. If the owner is alive, sleep for lockRetryInterval and retry.
//  4. If the owner is dead (stale lock), remove the file and immediately
//     retry the O_EXCL create. No sleep (the atomic create is the
//     tiebreaker if multiple processes race to reclaim).
func acquireLockFile(tokenPath string, log *zerolog.Logger) (*lockFile, error) {
	lockPath := tokenPath + ".lock"
	deadline := time.Now().Add(lockTimeout)
	lastURL := ""
	for {
		if time.Now().After(deadline) {
			return nil, fmt.Errorf("timed out waiting for lock file %s", lockPath)
		}
		content, err := createLockFile(lockPath)
		if err == nil {
			log.Debug().Str("path", lockPath).Msg("lock file acquired")
			return &lockFile{path: lockPath, content: content, log: log}, nil
		}
		if !os.IsExist(err) {
			return nil, errors.Wrapf(err, "failed to create lock file %s", lockPath)
		}

		// lock file exists, so check if the owner is still alive
		stale, content, checkErr := isLockFileStale(lockPath)
		if checkErr != nil {
			// file may be mid-write by another racer, or was removed
			// between our O_EXCL attempt and this read
			log.Debug().Err(checkErr).Str("path", lockPath).
				Msg("could not read lock file, retrying")
			time.Sleep(lockRetryInterval)

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Check for another running cloudflared process using the same token file and stop it if stale intent.
2. If the lock owner is truly gone but misreported, remove the stale .lock file manually.
3. Rerun the command once the holder exits; acquisition retries automatically until the timeout.

When it happens

Trigger: Thrown at token/token.go:129 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/67822d3741d11e0a. Report an issue: GitHub.