juanfont/headscale · error · ErrSystemChecksFailed

%w - see details above

Error message

%w - see details above

What it means

Sentinel error ErrSystemChecksFailed returned by the `hi doctor` command when at least one critical check has status statusFail. The doctor verifies the environment needed for Docker-based integration tests: Docker binary on PATH (exec.LookPath), Docker daemon reachability, Go toolchain, git repository state, and required repo files. The rendered message ends with '%!w(<nil>)'-free ' - see details above' because it wraps the sentinel; the actionable output is the per-check table printed by displayDoctorResults just before the return.

Source

Thrown at cmd/hi/doctor.go:89

		results = append(results, checkK3sImage(ctx))
	}

	// Check 3: Go installation
	results = append(results, checkGoInstallation(ctx))

	// Check 4: Git repository
	results = append(results, checkGitRepository(ctx))

	// Check 5: Required files
	results = append(results, checkRequiredFiles(ctx))

	// Display results
	displayDoctorResults(results)

	// Return error if any critical checks failed
	for _, result := range results {
		if result.Status == statusFail {
			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
		}
	}

	log.Printf("✅ All system checks passed - ready to run integration tests!")

	return nil
}

// checkDockerBinary verifies Docker binary is available.
func checkDockerBinary() DoctorResult {
	_, err := exec.LookPath("docker")
	if err != nil {
		return fail(
			"Docker Binary",
			"Docker binary not found in PATH",
			"Install Docker: https://docs.docker.com/get-docker/",
			"For macOS: consider using colima or Docker Desktop",
			"Ensure docker is in your PATH",

View on GitHub (pinned to 565fd254d0)

Solutions

1. Scroll up and read the doctor table — the row marked FAIL names the exact check; fix that check
2. Run `go run ./cmd/hi doctor` standalone to iterate on the environment without starting a test
3. Typical fixes: install/start Docker (`docker info` must succeed), ensure `docker` is on PATH, run from the repo root inside `nix develop`
4. Re-run `go run ./cmd/hi doctor` until it prints the all-checks-passed message

go run ./cmd/hi doctor  # exit 0 means all critical checks pass
# only then:
go run ./cmd/hi run "TestName"

if err := runDoctorCheck(ctx); err != nil {
    if errors.Is(err, ErrSystemChecksFailed) {
        // environment problem, not a code problem — fix env and retry, don't debug the test
        log.Fatalf("environment not ready; run 'hi doctor' for details")
    }
    return err
}

When it happens

Trigger: runDoctorCheck executing the check set and any result landing on statusFail — e.g. `docker` not found via exec.LookPath, daemon socket unreachable, not inside a git checkout, or missing required repo files.

Common situations: Fresh machine without Docker installed or not in PATH; Docker daemon not started; running `hi` from outside the headscale repository; nix dev shell not entered so auxiliary files/toolchain are absent.

Related errors

• pre-flight checks failed: %w
• ensuring image availability: %w
• creating container: %w
• starting container: %w
• executing test: %w

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