cloudflare/cloudflared · critical

unable to generate a connector UUID: %w

Error message

unable to generate a connector UUID: %w

What it means

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.

Source

Thrown at client/config.go:26

	"github.com/rs/zerolog"

	"github.com/cloudflare/cloudflared/features"
	"github.com/cloudflare/cloudflared/tunnelrpc/pogs"
)

// Config captures the local client runtime configuration.
type Config struct {
	ConnectorID uuid.UUID
	Version     string
	Arch        string

	featureSelector features.FeatureSelector
}

func NewConfig(version string, arch string, featureSelector features.FeatureSelector) (*Config, error) {
	connectorID, err := uuid.NewRandom()
	if err != nil {
		return nil, fmt.Errorf("unable to generate a connector UUID: %w", err)
	}
	return &Config{
		ConnectorID:     connectorID,
		Version:         version,
		Arch:            arch,
		featureSelector: featureSelector,
	}, nil
}

// ConnectionOptionsSnapshot is a snapshot of the current client information used to initialize a connection.
//
// The FeatureSnapshot is the features that are available for this connection. At the client level they may
// change, but they will not change within the scope of this struct.
type ConnectionOptionsSnapshot struct {
	client              pogs.ClientInfo
	originLocalIP       net.IP
	numPreviousAttempts uint8
	FeatureSnapshot     features.FeatureSnapshot

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Ensure /dev/urandom exists and is readable inside the container/VM (check `ls -l /dev/urandom`).
2. Relax seccomp/apparmor profiles that block the getrandom(2) syscall for the cloudflared process.
3. Restart the host or container to restore the entropy source, then retry starting the tunnel.
4. Upgrade cloudflared/kernel if running an old kernel lacking getrandom support.
5. Pin the ConnectorID via configuration if your environment requires deterministic identity, reducing dependence on runtime RNG at this path.

Example fix

// Docker: before
// securityOpt: ["seccomp=strict-profile-blocking-getrandom"]
// after
docker run --security-opt seccomp=default.json --device /dev/urandom:/dev/urandom cloudflare/cloudflared:latest tunnel run ...

if _, err := os.Stat("/dev/urandom"); err != nil {
	return fmt.Errorf("entropy source unavailable: %w", err)
}

cfg, err := client.NewConfig(version, arch, featureSelector)
if err != nil && strings.Contains(err.Error(), "unable to generate a connector UUID") {
	// entropy failure: surface environment problem, optionally retry once
	return fmt.Errorf("environment entropy source broken: %w", err)
}

When it happens

Trigger: 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.

Common situations: Running cloudflared inside minimal/seccomp-sandboxed containers where getrandom is blocked; low-entropy embedded environments; broken Docker/runc device mappings that hide /dev/urandom.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• allowed mail rule %d is empty
• allowed mail rule %q has an invalid wildcard domain
• allowed mail rule %q is not a valid email address
• unrecognized service: %s, %t
• failed to parse quick Tunnel ID

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/7883b8016d784512. Report an issue: GitHub.