juanfont/headscale · error

starting headscale container: %w\n\nUnable to get diagnostic

Error message

starting headscale container: %w\n\nUnable to get diagnostic build output (command may have failed silently)

What it means

Last diagnostic branch: the initial container start failed and the diagnostic build produced no output at all (buildOutput == ""), so the real cause could not be captured. The message wraps the original error and notes the diagnostic command may have failed silently. This usually indicates the failure happened before/without any build output — e.g. daemon communication issues or a build command that errored immediately.

Source

Thrown at integration/hsic/hsic.go:574

			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,
		hsic.hostMetricsPort,
	)

	// Write the CA certificates to the container

View on GitHub (pinned to 565fd254d0)

Solutions

1. Rely on the wrapped original err — the diagnostic produced nothing
2. Check docker daemon health (docker info) and dmesg/systemd for daemon restarts
3. Re-run once after the daemon is stable; if reproducible, capture docker build output manually with the same Dockerfile
4. Check disk space on the Docker data root

docker info > /dev/null || echo "daemon unhealthy — restart before running tests"

When it happens

Trigger: BuildAndRunWithBuildOptions fails and the retry build invocation itself crashes or writes nothing (exec failure, daemon disconnect, output buffer problem). The original err is the only real signal available.

Common situations: Docker daemon restarting or disconnecting mid-operation; disk full so output cannot be written; dockertest build command invocation broken after tool upgrades.

Related errors

• starting headscale container: %w\n\nDocker build failed. Las
• dumping config: %w
• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w
• writing TLS certificate to container: %w

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