juanfont/headscale · error

writing headscale config to container: %w

Error message

writing headscale config to container: %w

What it means

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.

Source

Thrown at integration/hsic/hsic.go:602

	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 {
			return nil, fmt.Errorf("writing TLS certificate to container: %w", err)
		}

		err = hsic.WriteFile(tlsKeyPath, hsic.tlsKey)
		if err != nil {
			return nil, fmt.Errorf("writing TLS key to container: %w", err)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect docker logs of the headscale container for an immediate exit/panic
2. Verify /etc/headscale exists in the image (docker run --rm <img> ls /etc/headscale)
3. Run `go run ./cmd/hi doctor` to validate the environment
4. Retry on a less loaded Docker host

// Verify image layout once, outside the hot path
docker run --rm <headscale-image> ls /etc/headscale/config.yaml

When it happens

Trigger: 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.

Common situations: Container entrypoint failing instantly (bad image); Docker under heavy load dropping exec sessions; custom Dockerfile not creating /etc/headscale.

Related errors

• writing TLS certificate to container: %w
• writing TLS key to container: %w
• writing %q: %w
• dumping config: %w
• resolving registry auth: %w

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