juanfont/headscale · error

writing TLS key to container: %w

Error message

writing TLS key to container: %w

What it means

Returned by the DERP integration-test helper when writing the DERPer's TLS private key (<hostname>.key under DERPerCertRoot) into the container fails. Same mechanism as the certificate writes: a container-exec file write that returned an error.

Source

Thrown at integration/dsic/dsic.go:282

	for i, cert := range dsic.caCerts {
		err = dsic.WriteFile(fmt.Sprintf("%s/user-%d.crt", caCertRoot, i), cert)
		if err != nil {
			return nil, fmt.Errorf("writing TLS certificate to container: %w", err)
		}
	}

	if len(dsic.tlsCert) != 0 {
		err = dsic.WriteFile(fmt.Sprintf("%s/%s.crt", DERPerCertRoot, dsic.hostname), dsic.tlsCert)
		if err != nil {
			return nil, fmt.Errorf("writing TLS certificate to container: %w", err)
		}
	}

	if len(dsic.tlsKey) != 0 {
		err = dsic.WriteFile(fmt.Sprintf("%s/%s.key", DERPerCertRoot, dsic.hostname), dsic.tlsKey)
		if err != nil {
			return nil, fmt.Errorf("writing TLS key to container: %w", err)
		}
	}

	return dsic, nil
}

// Shutdown stops and cleans up the DERPer container.
func (t *DERPServerInContainer) Shutdown() error {
	err := t.SaveLog("/tmp/control")
	if err != nil {
		log.Printf(
			"saving log from %s: %s",
			t.hostname,
			fmt.Errorf("saving log: %w", err),
		)
	}

	return t.pool.Purge(t.container)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Re-run the test — transient exec failures during container provisioning are the most common cause
2. Check container logs and confirm the DERPer stayed alive through the whole setup phase
3. Verify image permissions for the DERPer certificate directory if the failure is persistent

When it happens

Trigger: The final WriteFile call for the key material fails — container exited, key path not writable, or Docker exec error. Occurs only when tlsKey is non-empty (TLS-enabled DERPer test).

Common situations: DERPer container restarts mid-setup; image runs as a user without write access to the cert root; interrupted Docker daemon during heavy parallel integration runs.

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
• %s starting tailscale DERPer container (version: %s): %w
• DERPer is not ready: %w
• writing TLS key to container: %w

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