{"record":{"id":"72e85d55ad2a4eb7","repo":"juanfont/headscale","slug":"writing-headscale-config-to-container-w","errorCode":null,"errorMessage":"writing headscale config to container: %w","messagePattern":"writing headscale config to container: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":602,"sourceCode":"\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 {\n\t\t\treturn nil, fmt.Errorf(\"writing TLS certificate to container: %w\", err)\n\t\t}\n\n\t\terr = hsic.WriteFile(tlsKeyPath, hsic.tlsKey)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"writing TLS key to container: %w\", err)","sourceCodeStart":584,"sourceCodeEnd":620,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L584-L620","documentation":"Thrown when hsic.WriteFile cannot write /etc/headscale/config.yaml with MinimumConfigYAML() (plus option overrides) into the container. This is the primary configuration step of HeadscaleInContainer; failure means the container filesystem write failed, almost always because the container is not in a writable/running state.","triggerScenarios":"Writing the config right after container start: docker exec/cp fails because the container exited (crash-on-start), the daemon dropped the connection, or /etc/headscale is missing in a custom image.","commonSituations":"Container entrypoint failing instantly (bad image); Docker under heavy load dropping exec sessions; custom Dockerfile not creating /etc/headscale.","solutions":["Inspect docker logs of the headscale container for an immediate exit/panic","Verify /etc/headscale exists in the image (docker run --rm <img> ls /etc/headscale)","Run `go run ./cmd/hi doctor` to validate the environment","Retry on a less loaded Docker host"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify image layout once, outside the hot path\ndocker run --rm <headscale-image> ls /etc/headscale/config.yaml","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep /etc/headscale present in any custom headscale image","Check container logs immediately when config write fails — it usually died","Avoid mutating the entrypoint to exit before setup completes"],"tags":["integration-test","docker","configuration","file-copy"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}