What causes "Tunnel credentials file '%s' doesn't exist or is not a file" in cloudflare/cloudflared?

Verify the path with `ls -l ` and correct any typo in --cred-file or the credentials-file config field

Tunnel credentials file '%s' doesn't exist or is not a file

Error message

Tunnel credentials file '%s' doesn't exist or is not a file

What it means

staticPath is a CredFinder implementation that returns a fixed credentials-file path. Its Path() method returns this error when the configured path is empty or does not point to a readable regular file. Cloudflared needs the tunnel credentials JSON (containing the tunnel secret) to run a named tunnel.

Source

Thrown at cmd/cloudflared/tunnel/credential_finder.go:39

// Implements CredFinder and looks for the credentials file at the given
// filepath.
type staticPath struct {
	filePath string
	fs       fileSystem
}

func newStaticPath(filePath string, fs fileSystem) CredFinder {
	return staticPath{
		filePath: filePath,
		fs:       fs,
	}
}

func (a staticPath) Path() (string, error) {
	if a.filePath != "" && a.fs.validFilePath(a.filePath) {
		return a.filePath, nil
	}
	return "", fmt.Errorf("Tunnel credentials file '%s' doesn't exist or is not a file", a.filePath)
}

// Implements CredFinder and looks for the credentials file in several directories
// searching for a file named <id>.json
type searchByID struct {
	id  uuid.UUID
	c   *cli.Context
	log *zerolog.Logger
	fs  fileSystem
}

func newSearchByID(id uuid.UUID, c *cli.Context, log *zerolog.Logger, fs fileSystem) CredFinder {
	return searchByID{
		id:  id,
		c:   c,
		log: log,
		fs:  fs,
	}

View on GitHub (pinned to 2253eeeb25)

Solutions

Verify the path with `ls -l <path>` and correct any typo in --cred-file or the credentials-file config field
Re-copy the <tunnel-id>.json credentials file from the machine that created the tunnel (`cloudflared tunnel token <name>` also works for remote-managed tunnels)
If the file is truly lost, delete the tunnel (`cloudflared tunnel delete <name>`) and create a new one with `cloudflared tunnel create <name>`

Example fix

// before
$ cloudflared tunnel run --cred-file ~/.cloudflared/tunne1.json
// error: Tunnel credentials file '~/.cloudflared/tunne1.json' doesn't exist or is not a file

// after (fix typo or use the real ID)
$ cloudflared tunnel run --cred-file ~/.cloudflared/6ff42ae2-765d-4adf-8336-94d006239e8e.json

Defensive patterns

Strategy: validation

Validate before calling

if fi, err := os.Stat(credFile); err != nil || fi.IsDir() {
    return fmt.Errorf("credentials file %q missing or not a file", credFile)
}

Type guard

func credFileExists(p string) bool { fi, err := os.Stat(p); return err == nil && !fi.IsDir() }

Try / catch

path, err := credFinder.Path()
if err != nil {
    logger.Error().Err(err).Msg("cannot locate tunnel credentials")
    return err
}

Prevention

Mount or copy credentials into containers/services before first run and verify with a startup healthcheck
Use `cloudflared tunnel token <name>` / remote-managed tunnels to avoid local JSON files entirely
Keep credentials named <tunnel-id>.json in ~/.cloudflared so default discovery finds them

When it happens

Trigger: Running `cloudflared tunnel run --cred-file /path/to/creds.json` where the file does not exist, was deleted, or is a directory; or `TUNNEL_CRED_FILE` pointing at a non-file path.

Common situations: Credentials file deleted after tunnel cleanup, path typo, running cloudflared in a container without the credentials volume mounted, or copying the token but not the JSON credentials file to a new host.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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