{"record":{"id":"d3221b0bd64ace57","repo":"cloudflare/cloudflared","slug":"failed-to-create-tunnel-d3221b","errorCode":null,"errorMessage":"failed to create tunnel","messagePattern":"failed to create tunnel","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/subcommands.go","lineNumber":290,"sourceCode":"\treturn randomBytes, err\n}\n\nfunc createCommand(c *cli.Context) error {\n\tsc, err := newSubcommandContext(c)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"error setting up logger\")\n\t}\n\n\tif c.NArg() != 1 {\n\t\treturn cliutil.UsageError(`\"cloudflared tunnel create\" requires exactly 1 argument, the name of tunnel to create.`)\n\t}\n\tname := c.Args().First()\n\n\twarningChecker := updater.StartWarningCheck(c)\n\tdefer warningChecker.LogWarningIfAny(sc.log)\n\n\t_, err = sc.create(name, c.String(CredFileFlag), c.String(createSecretFlag.Name))\n\treturn errors.Wrap(err, \"failed to create tunnel\")\n}\n\nfunc tunnelFilePath(tunnelID uuid.UUID, directory string) (string, error) {\n\tfileName := fmt.Sprintf(\"%v.json\", tunnelID)\n\tfilePath := filepath.Clean(fmt.Sprintf(\"%s/%s\", directory, fileName))\n\treturn homedir.Expand(filePath)\n}\n\n// writeTunnelCredentials saves `credentials` as a JSON into `filePath`, only if\n// the file does not exist already\nfunc writeTunnelCredentials(filePath string, credentials *connection.Credentials) error {\n\tif _, err := os.Stat(filePath); !os.IsNotExist(err) {\n\t\tif err == nil {\n\t\t\treturn fmt.Errorf(\"%s already exists\", filePath)\n\t\t}\n\t\treturn err\n\t}\n\tbody, err := json.Marshal(credentials)","sourceCodeStart":272,"sourceCodeEnd":308,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/subcommands.go#L272-L308","documentation":"`cloudflared tunnel create` calls sc.create(name, credFile, secret) which talks to the Cloudflare API to provision the tunnel and then writes the credentials file. Any failure along that path is wrapped as 'failed to create tunnel'. This groups authentication errors, name conflicts, and local file write failures.","triggerScenarios":"Running `cloudflared tunnel create <name>` when: the name already exists in the account, the API client is unauthenticated (no cert.pem), the Cloudflare API returns a non-2xx response, or the credentials JSON cannot be written to the --cred-file location.","commonSituations":"Re-running create with a tunnel name that already exists; expired or missing origin certificate; running in a read-only home directory so the <tunnelID>.json cannot be written; API outages or 5xx responses.","solutions":["Read the wrapped cause under this message for the precise failure (auth, name conflict, or file write)","Pick a unique tunnel name or delete the existing tunnel via `cloudflared tunnel delete <name>`","Re-authenticate with `cloudflared tunnel login` if the cause indicates credentials/cert issues","Ensure the credentials output directory exists and is writable (or pass --cred-file to a writable path)"],"exampleFix":"// before\ncloudflared tunnel create my-tunnel   # name already exists\n// after\ncloudflared tunnel list && cloudflared tunnel create my-tunnel-2   # unique name","handlingStrategy":"try-catch","validationCode":"existing, _ := cloudflared(\"tunnel\", \"list\", \"--output\", \"json\")\nif strings.Contains(existing, \"\\\"name\\\": \\\"\"+name+\"\\\"\") {\n\treturn fmt.Errorf(\"tunnel %q already exists\", name)\n}","typeGuard":null,"tryCatchPattern":"if _, err := sc.create(name, credFile, secret); err != nil {\n\tvar conflict bool\n\tif strings.Contains(err.Error(), \"already exists\") { conflict = true }\n\treturn fmt.Errorf(\"failed to create tunnel: %w\", err)\n}","preventionTips":["Generate unique tunnel names (timestamp/suffix) in automation","Verify cert.pem validity before create (token expiry causes auth failures)","Pre-create a writable credentials directory or pass --cred-file explicitly","Handle Cloudflare API 5xx with a bounded retry around create"],"tags":["cloudflared","api","tunnel","cli"],"backgroundTag":"api-request-failed","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"}