juanfont/headscale · error

pre-flight checks failed: %w

Error message

pre-flight checks failed: %w

What it means

Wrapper around the `hi doctor` failure raised inside `hi run` before any test starts. runTestContainer is never reached: the pre-flight environment checks (Docker binary, daemon, Go version, git repo, required files) reported at least one statusFail, and this is the surfaced message. The wrapped error chain leads back to ErrSystemChecksFailed.

Source

Thrown at cmd/hi/run.go:55

		runConfig.TestPattern = args[0]
	}

	if runConfig.TestPattern == "" {
		return ErrTestPatternRequired
	}

	if runConfig.GoVersion == "" {
		runConfig.GoVersion = detectGoVersion()
	}

	// Run pre-flight checks
	if runConfig.Verbose {
		log.Printf("Running pre-flight system checks...")
	}

	err := runDoctorCheck(env.Context())
	if err != nil {
		return fmt.Errorf("pre-flight checks failed: %w", err)
	}

	if runConfig.Verbose {
		log.Printf("Running test: %s", runConfig.TestPattern)
		log.Printf("Go version: %s", runConfig.GoVersion)
		log.Printf("Timeout: %s", runConfig.Timeout)
		log.Printf("Use PostgreSQL: %t", runConfig.UsePostgres)
	}

	return runTestContainer(env.Context(), &runConfig)
}

// detectGoVersion reads the Go version from go.mod file.
func detectGoVersion() string {
	content, err := os.ReadFile("go.mod")
	if err != nil {
		content, err = os.ReadFile(filepath.Join("..", "..", "go.mod"))
		if err != nil {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `go run ./cmd/hi doctor` directly — its detailed table shows which check failed (the wrapper hides it behind 'see details above')
2. Start/repair Docker until `docker info` succeeds
3. Enter the nix dev shell (`nix develop`) and run from the repository root
4. Re-run `go run ./cmd/hi run "TestName"` once doctor passes

go run ./cmd/hi doctor >/dev/null 2>&1 || { echo 'fix environment first'; exit 1; }
go run ./cmd/hi run "TestName"

if err := runTest(env.Context()); err != nil {
    var pre *PreFlightError // or errors.Is against ErrSystemChecksFailed
    if errors.Is(err, ErrSystemChecksFailed) {
        // do not retry the test; repair the environment (docker, PATH, repo root)
    }
}

When it happens

Trigger: runDoctorCheck(env.Context()) returning an error — Docker not installed/running, missing toolchain, not in a git checkout, or missing required repo files — at the start of every `go run ./cmd/hi run` invocation.

Common situations: Forgetting to start Docker before running integration tests; CI runners missing the Docker socket; running hi outside the repo or outside `nix develop`; corrupted docker context after switching between Docker Desktop and rootless Docker.

Related errors

• ensuring image availability: %w
• creating container: %w
• extracting logs: %w
• %w - see details above
• cleaning stale test containers: %w

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