{"record":{"id":"2b6b3d7a17eaf47e","repo":"cloudflare/cloudflared","slug":"you-cannot-use-uuids-as-tunnel-names","errorCode":null,"errorMessage":"you cannot use UUIDs as tunnel names","messagePattern":"you cannot use UUIDs as tunnel names","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cfapi/tunnel.go","lineNumber":97,"sourceCode":"\treturn &CleanupParams{\n\t\tqueryParams: url.Values{},\n\t}\n}\n\nfunc (cp *CleanupParams) ForClient(clientID uuid.UUID) {\n\tcp.queryParams.Set(\"client_id\", clientID.String())\n}\n\nfunc (cp CleanupParams) encode() string {\n\treturn cp.queryParams.Encode()\n}\n\nfunc (r *RESTClient) CreateTunnel(name string, tunnelSecret []byte) (*TunnelWithToken, error) {\n\tif name == \"\" {\n\t\treturn nil, errors.New(\"tunnel name required\")\n\t}\n\tif _, err := uuid.Parse(name); err == nil {\n\t\treturn nil, errors.New(\"you cannot use UUIDs as tunnel names\")\n\t}\n\tbody := &newTunnel{\n\t\tName:         name,\n\t\tTunnelSecret: tunnelSecret,\n\t}\n\n\tresp, err := r.sendRequest(\"POST\", r.baseEndpoints.accountLevel, body)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"REST request failed\")\n\t}\n\tdefer resp.Body.Close()\n\n\tswitch resp.StatusCode {\n\tcase http.StatusOK:\n\t\tvar tunnel TunnelWithToken\n\t\tif serdeErr := parseResponse(resp.Body, &tunnel); serdeErr != nil {\n\t\t\treturn nil, serdeErr\n\t\t}","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cfapi/tunnel.go#L79-L115","documentation":"CreateTunnel rejects names that parse as valid UUIDs, returning this client-side validation error. This prevents ambiguity/collisions with tunnel IDs, which are themselves UUIDs. The check happens locally before any API call via uuid.Parse(name).","triggerScenarios":"Calling RESTClient.CreateTunnel with a name like \"123e4567-e89b-12d3-a456-426614174000\" that uuid.Parse accepts — e.g. using a UUID generator to name tunnels.","commonSituations":"Scripts auto-generating tunnel names with uuidgen or similar; accidentally passing a tunnel ID where a name is expected; templating bugs substituting the ID variable into the name field.","solutions":["Use a human-readable name that is not a UUID (prefix it, e.g. \"tunnel-<uuid>\")","Pass the tunnel ID to lookup APIs, not CreateTunnel","Sanitize generated names before calling CreateTunnel"],"exampleFix":"// before\nname := uuid.NewString()\ntunnel, err := client.CreateTunnel(name, secret)\n// after\nname := \"tunnel-\" + uuid.NewString()\ntunnel, err := client.CreateTunnel(name, secret)","handlingStrategy":"validation","validationCode":"if _, err := uuid.Parse(name); err == nil {\n    return errors.New(\"tunnel name must not be a UUID; prefix it, e.g. 'tunnel-<uuid>'\")\n}","typeGuard":null,"tryCatchPattern":"t, err := client.CreateTunnel(name, secret)\nif err != nil && strings.Contains(err.Error(), \"UUIDs as tunnel names\") {\n    return fmt.Errorf(\"rename tunnel: %w\", err)\n}","preventionTips":["Prefix generated names (e.g. 'tunnel-<uuid>') to guarantee they are not UUIDs","Never pass tunnel IDs where names are expected","Sanitize programmatically generated names before creation","Document naming conventions for tunnel provisioning scripts"],"tags":["validation","uuid","tunnel","cloudflare"],"backgroundTag":"invalid-argument-value","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}