{"record":{"id":"13132a725704f025","repo":"cloudflare/cloudflared","slug":"error-while-creating-backend-client","errorCode":null,"errorMessage":"error while creating backend client","messagePattern":"error while creating backend client","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/subcommand_context_teamnet.go","lineNumber":17,"sourceCode":"package tunnel\n\nimport (\n\t\"net\"\n\n\t\"github.com/google/uuid\"\n\t\"github.com/pkg/errors\"\n\n\t\"github.com/cloudflare/cloudflared/cfapi\"\n)\n\nconst noClientMsg = \"error while creating backend client\"\n\nfunc (sc *subcommandContext) listRoutes(filter *cfapi.IpRouteFilter) ([]*cfapi.DetailedRoute, error) {\n\tclient, err := sc.client()\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, noClientMsg)\n\t}\n\treturn client.ListRoutes(filter)\n}\n\nfunc (sc *subcommandContext) addRoute(newRoute cfapi.NewRoute) (cfapi.Route, error) {\n\tclient, err := sc.client()\n\tif err != nil {\n\t\treturn cfapi.Route{}, errors.Wrap(err, noClientMsg)\n\t}\n\treturn client.AddRoute(newRoute)\n}\n\nfunc (sc *subcommandContext) deleteRoute(id uuid.UUID) error {\n\tclient, err := sc.client()\n\tif err != nil {\n\t\treturn errors.Wrap(err, noClientMsg)\n\t}\n\treturn client.DeleteRoute(id)","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/subcommand_context_teamnet.go#L1-L35","documentation":"`listRoutes` wraps the error returned by `subcommandContext.client()` when constructing the Cloudflare API (Tunnel Store) client fails, using the shared noClientMsg text. Client construction fails when the origin certificate cannot be read or parsed, or the API URL is invalid — so no route listing can proceed.","triggerScenarios":"Running `cloudflared tunnel route ip list` (or any teamnet route command) where credentials.Read fails (missing/invalid ~/.cloudflared/cert.pem or --origincert path) or cred.Client() cannot build the client (bad --api-url, malformed cert).","commonSituations":"Running route commands on a CI box without having run `cloudflared tunnel login`; pointing --origincert at a tunnel credentials JSON instead of the origin cert; corrupt cert.pem; FIPS/fedramp endpoint misconfiguration.","solutions":["Run `cloudflared tunnel login` to generate a valid origin cert, or pass --origincert pointing at an existing cert.pem","Verify the cert file exists and is readable at the configured path (default ~/.cloudflared/cert.pem)","Check --api-url points to a valid Cloudflare API endpoint","Confirm the command runs as a user with access to the cert file"],"exampleFix":"// before (no guard — error surfaces late)\nclient, err := sc.client()\nif err != nil {\n    return nil, errors.Wrap(err, noClientMsg)\n}\n// after (check credentials before invoking the command)\nif _, err := os.Stat(origincertPath); err != nil {\n    return nil, fmt.Errorf(\"origin cert not found at %s; run `cloudflared tunnel login` first\", origincertPath)\n}","handlingStrategy":"validation","validationCode":"certPath := \"/root/.cloudflared/cert.pem\"\nif info, err := os.Stat(certPath); err != nil || info.IsDir() {\n    return errors.New(\"origin cert missing; run `cloudflared tunnel login`\")\n}","typeGuard":null,"tryCatchPattern":"routes, err := listRoutes(filter)\nif err != nil && strings.Contains(err.Error(), \"error while creating backend client\") {\n    // credentials problem — re-login or fix --origincert before retrying\n}","preventionTips":["Run `cloudflared tunnel login` before any tunnel/route/vnet command","Pass an explicit --origincert in scripts and CI instead of relying on $HOME","Mount and chmod 600 the cert.pem in containers","Never point --origincert at a tunnel credentials JSON; it must be cert.pem"],"tags":["go","cli","cloudflare-api","authentication"],"backgroundTag":"missing-credentials","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"}