What causes "tunnel credentials file not found" in cloudflare/cloudflared?

Copy the tunnel's .json credentials file into ~/.cloudflared/ (or the configured origincert directory)

tunnel credentials file not found

Error message

tunnel credentials file not found

What it means

searchByID is a CredFinder that looks for a file named <tunnel-id>.json in the default config directories (e.g. the origin cert directory and ~/.cloudflared). If no such file exists in any searched location, Path() returns this generic not-found error. It is the fallback path resolution when no explicit --cred-file is given.

Source

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

		if originCertPath, err := credentials.FindOriginCert(originCertPath, &originCertLog); err == nil {
			originCertDir := filepath.Dir(originCertPath)
			if filePath, err := tunnelFilePath(s.id, originCertDir); err == nil {
				if s.fs.validFilePath(filePath) {
					return filePath, nil
				}
			}
		}
	}

	// Last resort look under default config directories
	for _, configDir := range config.DefaultConfigSearchDirectories() {
		if filePath, err := tunnelFilePath(s.id, configDir); err == nil {
			if s.fs.validFilePath(filePath) {
				return filePath, nil
			}
		}
	}
	return "", fmt.Errorf("tunnel credentials file not found")
}

View on GitHub (pinned to 2253eeeb25)

Solutions

Copy the tunnel's <id>.json credentials file into ~/.cloudflared/ (or the configured origincert directory)
Pass the explicit location with `cloudflared tunnel run --cred-file /path/to/<id>.json`
Verify you are running as the same user that created the tunnel, or fix the service unit's HOME/User setting

Example fix

// before (systemd unit, no credentials in service user's home)
ExecStart=/usr/local/bin/cloudflared tunnel run mytunnel

// after
ExecStart=/usr/local/bin/cloudflared tunnel --cred-file /etc/cloudflared/<tunnel-id>.json tunnel run mytunnel

Defensive patterns

Strategy: fallback

Validate before calling

matches, _ := filepath.Glob(filepath.Join("~/.cloudflared", tunnelID+".json"))
if len(matches) == 0 {
    return fmt.Errorf("no credentials for tunnel %s; pass --cred-file", tunnelID)
}

Type guard

func tunnelCredsDiscoverable(id string, dirs ...string) bool {
    for _, d := range dirs {
        if fi, err := os.Stat(filepath.Join(d, id+".json")); err == nil && !fi.IsDir() { return true }
    }
    return false
}

Try / catch

path, err := searchByID{id: tunnelID}.Path()
if err != nil {
    logger.Error().Err(err).Msg("credentials not found; pass --cred-file explicitly")
    return err
}

Prevention

Always pass --cred-file in service/systemd/container environments where HOME may differ
Provision credentials with configuration management (Ansible etc.) so they exist on every host
Run cloudflared as the same user that created the tunnel, or store creds in a shared path

When it happens

Trigger: Running `cloudflared tunnel run <name-or-id>` without --cred-file when the default originCertPath/config dirs contain no `<uuid>.json` for that tunnel ID, or tunnelFilePath lookup fails.

Common situations: Running the tunnel on a machine other than the one that created it; tunnel created in a different user's home directory; credentials deleted by cleanup scripts; running as a service user (e.g. systemd) whose HOME differs from the creator's.

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/d79972730869c092. Report an issue: GitHub.