juanfont/headscale · error

creating default TLS certificates: %w

Error message

creating default TLS certificates: %w

What it means

Returned from HeadscaleInContainer construction when integrationutil.CreateCertificate(hsic.hostname) fails. TLS is on by default for integration tests; if neither WithoutTLS nor WithCustomTLS was set, hsic generates a self-signed CA + server certificate for the container hostname. Failure means the cert-generation utility (crypto/x509 chain building, PEM encoding, key generation) errored.

Source

Thrown at integration/hsic/hsic.go:375

		networks: networks,

		env:              DefaultConfigEnv(),
		filesInContainer: []fileInContainer{},
		policyMode:       types.PolicyModeFile,
	}

	for _, opt := range opts {
		opt(hsic)
	}

	// TLS is enabled by default for all integration tests.
	// Generate a self-signed certificate if TLS was not explicitly
	// disabled via [WithoutTLS] and no custom cert was provided
	// via [WithCustomTLS].
	if !hsic.noTLS && len(hsic.tlsCert) == 0 {
		caCert, cert, key, err := integrationutil.CreateCertificate(hsic.hostname)
		if err != nil {
			return nil, fmt.Errorf("creating default TLS certificates: %w", err)
		}

		hsic.tlsCACert = caCert
		hsic.tlsCert = cert
		hsic.tlsKey = key

		// Install the CA cert into the headscale container's trust
		// store so that tools like curl trust the server's own
		// certificate.
		hsic.caCerts = append(hsic.caCerts, caCert)
	}

	log.Println("NAME: ", hsic.hostname)

	portProto := fmt.Sprintf("%d/tcp", hsic.port)

	headscaleBuildOptions := &dockertest.BuildOptions{
		Dockerfile: IntegrationTestDockerFileName,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped crypto error — most often 'x509: hostname is not a valid DNS name'
2. Ensure a valid container hostname (default hsic hostname or WithTLSHostname with a legal DNS label)
3. As a workaround, supply certs via WithCustomTLS or disable TLS via WithoutTLS
4. Check the CreateCertificate helper in integration/util for its hostname validation

Example fix

// workaround for an invalid custom hostname
// before
hsic.WithTLSHostname("my host"),
// after
hsic.WithTLSHostname("my-host"),

// Validate hostname before container construction (cheap guard)
if !isValidDNSLabel(hsicHostname) { return nil, fmt.Errorf("invalid hostname %q", hsicHostname) }

When it happens

Trigger: Calling hsic.NewHeadscaleInContainer(...) without WithCustomTLS/WithoutTLS on a host where the certificate helper fails: invalid/empty hostname making SANs invalid, entropy exhaustion during key generation, or a bug in the cert template.

Common situations: Hostname option producing an empty or illegal DNS name (WithTLSHostname with invalid chars); extremely locked-down CI runners with depleted entropy; rarely, x509 template errors after Go upgrades.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• creating certificates for derp test: %w
• writing TLS certificate to container: %w
• writing TLS key to container: %w
• writing TLS key to container: %w
• no cert domains available for HTTPS

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/b6999025e26a482b. Report an issue: GitHub.