What causes "error writing token credentials to JSON file in path %s" in cloudflare/cloudflared?

Create the parent directory first: mkdir -p $(dirname ).

error writing token credentials to JSON file in path %s

Error message

error writing token credentials to JSON file in path %s

What it means

After fetching the tunnel token, tokenCommand optionally persists the decoded credentials as a JSON file when --cred-file is set. writeTunnelCredentials failing (serialization or file write) is wrapped with the target path in this message. It indicates the credentials JSON could not be written to the requested path.

Source

Thrown at cmd/cloudflared/tunnel/subcommands.go:888

	if c.NArg() != 1 {
		return cliutil.UsageError(`"cloudflared tunnel token" requires exactly 1 argument, the name or UUID of tunnel to fetch the credentials token for.`)
	}
	tunnelID, err := sc.findID(c.Args().First())
	if err != nil {
		return errors.Wrap(err, "error parsing tunnel ID")
	}

	token, err := sc.getTunnelTokenCredentials(tunnelID)
	if err != nil {
		return err
	}

	if path := c.String(CredFileFlag); path != "" {
		credentials := token.Credentials()
		err := writeTunnelCredentials(path, &credentials)
		if err != nil {
			return errors.Wrapf(err, "error writing token credentials to JSON file in path %s", path)
		}

		return nil
	}

	encodedToken, err := token.Encode()
	if err != nil {
		return err
	}

	fmt.Println(encodedToken)
	return nil
}

func buildRouteCommand() *cli.Command {
	return &cli.Command{
		Name:      "route",
		Usage:     "Define which traffic routed from Cloudflare edge to this tunnel: requests to a DNS hostname, to a Cloudflare Load Balancer, or traffic originating from Cloudflare WARP clients",

View on GitHub (pinned to 2253eeeb25)

Solutions

Create the parent directory first: mkdir -p $(dirname <path>).
Check write permissions on the target directory for the user running cloudflared.
Write to a writable location (e.g. /etc/cloudflared or the user's home) and move the file with elevated permissions.
Omit --cred-file and capture the encoded token on stdout instead.

Example fix

// before
cloudflared tunnel token --cred-file /etc/cloudflared/creds.json my-tunnel
// after
sudo mkdir -p /etc/cloudflared && sudo chown $(whoami) /etc/cloudflared
cloudflared tunnel token --cred-file /etc/cloudflared/creds.json my-tunnel

Defensive patterns

Strategy: validation

Validate before calling

// Go: verify the destination is writable before invoking the command
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
	return err
}
f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, 0o600)
if err == nil {
	f.Close()
}

Prevention

Pre-create and chown the credentials directory before running the command.
Run cloudflared as the same user that owns the config directory.
Avoid --cred-file on read-only container filesystems.

When it happens

Trigger: Running `cloudflared tunnel token --cred-file /path/creds.json <tunnel>` where the path's directory does not exist, the process lacks write permission, the path is a directory, or the disk is full.

Common situations: Pointing --cred-file at a read-only mount, a typo'd directory in the path, running under a service account without permission to the config directory, or container filesystems with a read-only root.

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

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