{"record":{"id":"7883b8016d784512","repo":"cloudflare/cloudflared","slug":"unable-to-generate-a-connector-uuid-w","errorCode":null,"errorMessage":"unable to generate a connector UUID: %w","messagePattern":"unable to generate a connector UUID: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/config.go","lineNumber":26,"sourceCode":"\t\"github.com/rs/zerolog\"\n\n\t\"github.com/cloudflare/cloudflared/features\"\n\t\"github.com/cloudflare/cloudflared/tunnelrpc/pogs\"\n)\n\n// Config captures the local client runtime configuration.\ntype Config struct {\n\tConnectorID uuid.UUID\n\tVersion     string\n\tArch        string\n\n\tfeatureSelector features.FeatureSelector\n}\n\nfunc NewConfig(version string, arch string, featureSelector features.FeatureSelector) (*Config, error) {\n\tconnectorID, err := uuid.NewRandom()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to generate a connector UUID: %w\", err)\n\t}\n\treturn &Config{\n\t\tConnectorID:     connectorID,\n\t\tVersion:         version,\n\t\tArch:            arch,\n\t\tfeatureSelector: featureSelector,\n\t}, nil\n}\n\n// ConnectionOptionsSnapshot is a snapshot of the current client information used to initialize a connection.\n//\n// The FeatureSnapshot is the features that are available for this connection. At the client level they may\n// change, but they will not change within the scope of this struct.\ntype ConnectionOptionsSnapshot struct {\n\tclient              pogs.ClientInfo\n\toriginLocalIP       net.IP\n\tnumPreviousAttempts uint8\n\tFeatureSnapshot     features.FeatureSnapshot","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/client/config.go#L8-L44","documentation":"NewConfig generates the connector's UUID via uuid.NewRandom and wraps any failure as 'unable to generate a connector UUID'. This almost always indicates the system's entropy source (/dev/urandom or getrandom(2)) is unavailable, since uuid generation is otherwise deterministic and reliable.","triggerScenarios":"Calling client.NewConfig (directly or via prepareTunnelConfig when starting a tunnel) on a system where the crypto/rand entropy source fails — e.g. a container with restricted /dev/urandom access or a heavily degraded kernel.","commonSituations":"Running cloudflared inside minimal/seccomp-sandboxed containers where getrandom is blocked; low-entropy embedded environments; broken Docker/runc device mappings that hide /dev/urandom.","solutions":["Ensure /dev/urandom exists and is readable inside the container/VM (check `ls -l /dev/urandom`).","Relax seccomp/apparmor profiles that block the getrandom(2) syscall for the cloudflared process.","Restart the host or container to restore the entropy source, then retry starting the tunnel.","Upgrade cloudflared/kernel if running an old kernel lacking getrandom support.","Pin the ConnectorID via configuration if your environment requires deterministic identity, reducing dependence on runtime RNG at this path."],"exampleFix":"// Docker: before\n// securityOpt: [\"seccomp=strict-profile-blocking-getrandom\"]\n// after\ndocker run --security-opt seccomp=default.json --device /dev/urandom:/dev/urandom cloudflare/cloudflared:latest tunnel run ...","handlingStrategy":"retry","validationCode":"if _, err := os.Stat(\"/dev/urandom\"); err != nil {\n\treturn fmt.Errorf(\"entropy source unavailable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"cfg, err := client.NewConfig(version, arch, featureSelector)\nif err != nil && strings.Contains(err.Error(), \"unable to generate a connector UUID\") {\n\t// entropy failure: surface environment problem, optionally retry once\n\treturn fmt.Errorf(\"environment entropy source broken: %w\", err)\n}","preventionTips":["Ensure /dev/urandom is present and readable in containers","Avoid seccomp profiles blocking getrandom(2)","Retry config creation once on transient RNG failure"],"tags":["go","uuid","entropy","config"],"backgroundTag":"missing-env-var","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"}