{"record":{"id":"6fc2ddf8ad6d92ad","repo":"juanfont/headscale","slug":"writing-tls-certificate-to-container-w-6fc2dd","errorCode":null,"errorMessage":"writing TLS certificate to container: %w","messagePattern":"writing TLS certificate to container: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":596,"sourceCode":"\tlog.Printf(\"Created %s container\\n\", hsic.hostname)\n\n\thsic.container = container\n\n\t// Get the dynamically assigned host port for metrics/pprof\n\thsic.hostMetricsPort = container.GetHostPort(\"9090/tcp\")\n\n\tlog.Printf(\n\t\t\"Headscale %s metrics available at http://localhost:%s/metrics (debug at http://localhost:%s/debug/)\\n\",\n\t\thsic.hostname,\n\t\thsic.hostMetricsPort,\n\t\thsic.hostMetricsPort,\n\t)\n\n\t// Write the CA certificates to the container\n\tfor i, cert := range hsic.caCerts {\n\t\terr = hsic.WriteFile(fmt.Sprintf(\"%s/user-%d.crt\", caCertRoot, i), cert)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"writing TLS certificate to container: %w\", err)\n\t\t}\n\t}\n\n\terr = hsic.WriteFile(\"/etc/headscale/config.yaml\", []byte(MinimumConfigYAML()))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"writing headscale config to container: %w\", err)\n\t}\n\n\tif hsic.aclPolicy != nil {\n\t\terr = hsic.writePolicy(hsic.aclPolicy)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"writing policy: %w\", err)\n\t\t}\n\t}\n\n\tif hsic.hasTLS() {\n\t\terr = hsic.WriteFile(tlsCertPath, hsic.tlsCert)\n\t\tif err != nil {","sourceCodeStart":578,"sourceCodeEnd":614,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L578-L614","documentation":"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.","triggerScenarios":"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.","commonSituations":"Container crashed immediately after start (bad entrypoint); race between container start and file writes; custom headscale image missing /usr/local/share/ca-certificates.","solutions":["Confirm the headscale container is still running (docker ps) at failure time","Check container logs for an early crash before setup completed","Verify the base image contains /usr/local/share/ca-certificates (standard on Debian-based images)","Re-run; transient exec failures often clear on a healthy daemon"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Ensure container is running before setup writes\ncode, _ := hsic.ExitCodeOrState()\nif code != 0 && !hsic.Running() { return nil, fmt.Errorf(\"container died during setup\") }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Watch for containers that crash immediately after start — read docker logs early","Use Debian-based images that ship /usr/local/share/ca-certificates","Fail fast on the first in-container write failure rather than retrying setup"],"tags":["integration-test","docker","ca-certificates","file-copy"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}