juanfont/headscale · error

writing TLS certificate to container: %w

Error message

writing TLS certificate to container: %w

What it means

Raised during HeadscaleInContainer setup when hsic.WriteFile fails to install a CA certificate into the container at /usr/local/share/ca-certificates/user-<i>.crt (caCertRoot). WriteFile copies bytes into the running container via docker exec/cp; failure means the copy command failed or the target path is not writable.

Source

Thrown at integration/hsic/hsic.go:596

	log.Printf("Created %s container\n", hsic.hostname)

	hsic.container = container

	// Get the dynamically assigned host port for metrics/pprof
	hsic.hostMetricsPort = container.GetHostPort("9090/tcp")

	log.Printf(
		"Headscale %s metrics available at http://localhost:%s/metrics (debug at http://localhost:%s/debug/)\n",
		hsic.hostname,
		hsic.hostMetricsPort,
		hsic.hostMetricsPort,
	)

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

	err = hsic.WriteFile("/etc/headscale/config.yaml", []byte(MinimumConfigYAML()))
	if err != nil {
		return nil, fmt.Errorf("writing headscale config to container: %w", err)
	}

	if hsic.aclPolicy != nil {
		err = hsic.writePolicy(hsic.aclPolicy)
		if err != nil {
			return nil, fmt.Errorf("writing policy: %w", err)
		}
	}

	if hsic.hasTLS() {
		err = hsic.WriteFile(tlsCertPath, hsic.tlsCert)
		if err != nil {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Confirm the headscale container is still running (docker ps) at failure time
2. Check container logs for an early crash before setup completed
3. Verify the base image contains /usr/local/share/ca-certificates (standard on Debian-based images)
4. Re-run; transient exec failures often clear on a healthy daemon

// Ensure container is running before setup writes
code, _ := hsic.ExitCodeOrState()
if code != 0 && !hsic.Running() { return nil, fmt.Errorf("container died during setup") }

When it happens

Trigger: Any hsic.caCerts entry (the auto-generated CA from error 667, or certs added via options) failing to copy into the container: container exited before the write, docker exec failed, or the ca-certificates directory does not exist in the image.

Common situations: Container crashed immediately after start (bad entrypoint); race between container start and file writes; custom headscale image missing /usr/local/share/ca-certificates.

Understand the failure class

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

Related errors

• writing headscale config to container: %w
• writing TLS key to container: %w
• writing %q: %w
• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w

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