cloudflare/cloudflared · error

write token to %s: %w

Error message

write token to %s: %w

What it means

This error wraps the failure of os.WriteFile when persisting an access token into the cloudflared configuration directory (path 0600). It is thrown by writeTokenToFile after the token file has been created, meaning the file exists but writing its contents failed. The wrapped error (%w) carries the underlying OS reason (permissions, disk full, etc.).

Source

Thrown at cmd/cloudflared/common_service.go:62

	return nil
}

// Write out the token file to the configuration directory with the correct
// permissions. Since the method used to restrict the permissions is platform
// dependent, make the function used to restrict the permissions an injectable
// dependency
func writeTokenToFile(path string, token string) error {
	if _, err := tunnel.ParseToken(token); err != nil {
		return cliutil.UsageError("Provided tunnel token is not valid (%s).", err)
	}

	if err := createTokenFile(path); err != nil {
		return fmt.Errorf("create token file at %s: %w", path, err)
	}

	// Won't update permissions as file already exists
	if err := os.WriteFile(path, []byte(token), 0o600); err != nil {
		return fmt.Errorf("write token to %s: %w", path, err)
	}

	return nil
}

func removeTokenFile(configDir string, log *zerolog.Logger) {
	tp := tokenPath(configDir)
	err := os.Remove(tp)

	if err != nil && !errors.Is(err, os.ErrNotExist) {
		log.Warn().Msgf("Could not remove service token file at %s: %v", tp, err)
	}
}

func buildArgsForTokenFile(configDir string) []string {
	return []string{
		"tunnel", "run", "--token-file", tokenPath(configDir),
	}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Check free disk space (df -h) and quotas; free space if full.
2. Verify the config directory permissions (e.g. /etc/cloudflared or ~/.cloudflared) allow writing as the current user: ls -ld <dir>.
3. Check the filesystem is not mounted read-only (mount | grep <dir>) and remount read-write.
4. Look at the wrapped OS error text in the log to identify the exact cause (EACCES, ENOSPC, etc.).
5. If security software (SELinux/AppArmor) is blocking writes, adjust policy or use a permitted config directory via --config.

Example fix

// before: running as non-root user
cloudflared tunnel token --cred-file /etc/cloudflared/token.json <tunnel>
// after: run as root or point at a writable dir
sudo cloudflared tunnel token --cred-file /etc/cloudflared/token.json <tunnel>

// before invoking install/token write
if st, err := os.Stat(configDir); err != nil || !st.IsDir() { return fmt.Errorf("config dir %s missing", configDir) }
if err := unix.Access(configDir, unix.W_OK); err != nil { return fmt.Errorf("config dir %s not writable: %w", configDir, err) }

func isWritableDir(path string) bool {
	st, err := os.Stat(path)
	return err == nil && st.IsDir() && unix.Access(path, unix.W_OK) == nil
}

if err := writeTokenToConfigDir(ctx, dir); err != nil {
	var pe *fs.PathError
	if errors.As(err, &pe) {
		log.Error().Str("op", pe.Op).Str("path", pe.Path).Err(pe.Err).Msg("token write failed")
	}
	return fmt.Errorf("token persistence failed: %w", err)
}

When it happens

Trigger: Calling writeTokenToConfigDir (e.g. via `cloudflared tunnel token` or token-based service install) when os.WriteFile fails: filesystem became read-only, disk full, another process holds a conflicting lock, or the path is a directory/not writable despite createTokenFile succeeding.

Common situations: Disk quota exceeded on the host; /etc/cloudflared or user config dir on a read-only mount; token written concurrently by another cloudflared instance; SELinux/AppArmor blocking writes to the config directory.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• ErrManagedLogNotFound
• could not write token to configuration directory: %w
• write token to configuration directory at %s: %w
• failed to create lock file %s
• failed to generate app token file path

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