juanfont/headscale · error

starting headscale container: %w\n\nDocker build succeeded o

Error message

starting headscale container: %w\n\nDocker build succeeded on retry, but container creation failed. Last %d lines of build output:\n%s

What it means

Diagnostic variant when the initial container start failed but the diagnostic rebuild SUCCEEDED (buildOutput != "", buildErr == nil). This means the image builds cleanly, yet container creation from it failed — the wrapped err is a runtime problem (port allocation, network creation, capability flags, name collision), not a build problem.

Source

Thrown at integration/hsic/hsic.go:570

			lines := strings.Split(buildOutput, "\n")

			const maxLines = 100

			startLine := 0
			if len(lines) > maxLines {
				startLine = len(lines) - maxLines
			}

			relevantOutput := strings.Join(lines[startLine:], "\n")

			if buildErr != nil {
				// The diagnostic build also failed - this is the real error
				return nil, fmt.Errorf("starting headscale container: %w\n\nDocker build failed. Last %d lines of output:\n%s", err, maxLines, relevantOutput)
			}

			if buildOutput != "" {
				// Build succeeded on retry but container creation still failed
				return nil, fmt.Errorf("starting headscale container: %w\n\nDocker build succeeded on retry, but container creation failed. Last %d lines of build output:\n%s", err, maxLines, relevantOutput)
			}

			// No output at all - diagnostic build command may have failed
			return nil, fmt.Errorf("starting headscale container: %w\n\nUnable to get diagnostic build output (command may have failed silently)", err)
		}
	}

	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,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Focus on the wrapped run error, not the build output — the image built successfully
2. Check the Docker network supports IPv6 (dockertestutil.DockerAllowLocalIPv6 requirement)
3. Remove stale containers/networks: `go run ./cmd/hi cleanup` or docker rm leftover containers
4. On rootless/restricted Docker, ensure NET_ADMIN capability is permitted

// Check the host Docker network supports IPv6 before suites needing it
docker network inspect <net> --format '{{.EnableIPv6}}'

When it happens

Trigger: BuildAndRunWithBuildOptions fails at the run stage: DockerRestartPolicy/DockerAllowLocalIPv6/DockerAllowNetworkAdministration options rejected (e.g. IPv6 disabled on the host or no NET_ADMIN capability), duplicate container name, or host port exhaustion; the subsequent diagnostic build succeeds, proving the image is fine.

Common situations: Docker daemon without IPv6 support; rootless Docker or restricted environments denying network-administration capability; leftover containers with the same auto-generated name from a crashed run.

Related errors

• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w
• writing TLS certificate to container: %w
• writing TLS key to container: %w
• DERPer is not ready: %w

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