cloudflare/cloudflared · error

failed to acquire app token lock

Error message

failed to acquire app token lock

What it means

getToken wraps this error when acquireLockFile cannot secure the app-token lock file for reasons other than benign contention (mirrors the lock-creation failure path). The lock serializes concurrent token fetches for the same app across processes; without it, concurrent processes could write conflicting token files.

Source

Thrown at token/token.go:348

// it appends the host of the appURL as the redirect URL to the access cli request if opening the browser
func FetchToken(appURL *url.URL, appInfo *AppInfo, autoClose bool, isFedramp bool, log *zerolog.Logger) (string, error) {
	return getToken(appURL, appInfo, true, autoClose, isFedramp, log)
}

// getToken will either load a stored token or generate a new one
func getToken(appURL *url.URL, appInfo *AppInfo, useHostOnly bool, autoClose bool, isFedramp bool, log *zerolog.Logger) (string, error) {
	if token, err := GetAppTokenIfExists(appInfo); token != "" && err == nil {
		return token, nil
	}

	appTokenPath, err := GenerateAppTokenFilePathFromURL(appInfo.AppHostname, appInfo.AppAUD, keyName)
	if err != nil {
		return "", errors.Wrap(err, "failed to generate app token file path")
	}

	appTokenLock, err := acquireLockFile(appTokenPath, log)
	if err != nil {
		return "", errors.Wrap(err, "failed to acquire app token lock")
	}
	defer appTokenLock.release()

	// check to see if another process has gotten a token while we waited for the lock
	if token, err := GetAppTokenIfExists(appInfo); token != "" && err == nil {
		return token, nil
	}

	// If an app token couldn't be found on disk, check for an org token and attempt to exchange it for an app token.
	var orgTokenPath string
	orgToken, orgTokenErr := GetOrgTokenIfExists(appInfo.AuthDomain)
	if orgTokenErr != nil {
		orgTokenPath, err = generateOrgTokenFilePathFromURL(appInfo.AuthDomain)
		if err != nil {
			return "", errors.Wrap(err, "failed to generate org token file path")
		}

		orgTokenLock, orgLockErr := acquireLockFile(orgTokenPath, log)

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Fix ownership/permissions of the token directory: mkdir -p ~/.cloudflared && sudo chown -R $USER ~/.cloudflared
2. Run cloudflared as the same user consistently (avoid mixing sudo and non-sudo runs)
3. Check disk space and filesystem writability for the user's home
4. Inspect the wrapped underlying error for the exact errno and resolve it

Example fix

// shell: repair a root-owned token directory
sudo chown -R $(id -u):$(id -g) ~/.cloudflared
chmod 700 ~/.cloudflared

// ensure the lock directory is writable by the effective user
import "golang.org/x/sys/unix"
if err := unix.Access(homeDir+"/.cloudflared", unix.W_OK); err != nil {
	return fmt.Errorf("token dir not writable: %v — run: sudo chown -R $USER ~/.cloudflared", err)
}

token, err := FetchToken(...)
if err != nil && strings.Contains(err.Error(), "failed to acquire app token lock") {
	// permission/environment problem; surface remediation hint
	return fmt.Errorf("%w (hint: chown ~/.cloudflared to the running user)", err)
}

When it happens

Trigger: FetchToken / FetchTokenWithRedirect -> getToken -> acquireLockFile(appTokenPath) returning a non-EEXIST error: unwritable token directory, stale permissions, disk full, or path issues — i.e. the lock file cannot be created at all.

Common situations: ~/.cloudflased (sic) or ~/.cloudflared owned by root after a sudo run; running the service under a different user (systemd User=) that cannot write the token dir; container with read-only home; SELinux/AppArmor denials.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

• failed to create lock file %s
• failed to acquire org token lock
• failed to write app token to disk
• failed to write org token to disk
• The file-writing error is: %v / The delete tunnel error is:

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