{"record":{"id":"d79972730869c092","repo":"cloudflare/cloudflared","slug":"tunnel-credentials-file-not-found","errorCode":null,"errorMessage":"tunnel credentials file not found","messagePattern":"tunnel credentials file not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/credential_finder.go","lineNumber":86,"sourceCode":"\t\tif originCertPath, err := credentials.FindOriginCert(originCertPath, &originCertLog); err == nil {\n\t\t\toriginCertDir := filepath.Dir(originCertPath)\n\t\t\tif filePath, err := tunnelFilePath(s.id, originCertDir); err == nil {\n\t\t\t\tif s.fs.validFilePath(filePath) {\n\t\t\t\t\treturn filePath, nil\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// Last resort look under default config directories\n\tfor _, configDir := range config.DefaultConfigSearchDirectories() {\n\t\tif filePath, err := tunnelFilePath(s.id, configDir); err == nil {\n\t\t\tif s.fs.validFilePath(filePath) {\n\t\t\t\treturn filePath, nil\n\t\t\t}\n\t\t}\n\t}\n\treturn \"\", fmt.Errorf(\"tunnel credentials file not found\")\n}\n","sourceCodeStart":68,"sourceCodeEnd":88,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/credential_finder.go#L68-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (systemd unit, no credentials in service user's home)\nExecStart=/usr/local/bin/cloudflared tunnel run mytunnel\n\n// after\nExecStart=/usr/local/bin/cloudflared tunnel --cred-file /etc/cloudflared/<tunnel-id>.json tunnel run mytunnel","handlingStrategy":"fallback","validationCode":"matches, _ := filepath.Glob(filepath.Join(\"~/.cloudflared\", tunnelID+\".json\"))\nif len(matches) == 0 {\n    return fmt.Errorf(\"no credentials for tunnel %s; pass --cred-file\", tunnelID)\n}","typeGuard":"func tunnelCredsDiscoverable(id string, dirs ...string) bool {\n    for _, d := range dirs {\n        if fi, err := os.Stat(filepath.Join(d, id+\".json\")); err == nil && !fi.IsDir() { return true }\n    }\n    return false\n}","tryCatchPattern":"path, err := searchByID{id: tunnelID}.Path()\nif err != nil {\n    logger.Error().Err(err).Msg(\"credentials not found; pass --cred-file explicitly\")\n    return err\n}","preventionTips":["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"],"tags":["file","tunnel","configuration"],"backgroundTag":"file-not-found","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}