{"record":{"id":"3aa87e24ca704587","repo":"juanfont/headscale","slug":"pre-flight-checks-failed-w","errorCode":null,"errorMessage":"pre-flight checks failed: %w","messagePattern":"pre-flight checks failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/hi/run.go","lineNumber":55,"sourceCode":"\t\trunConfig.TestPattern = args[0]\n\t}\n\n\tif runConfig.TestPattern == \"\" {\n\t\treturn ErrTestPatternRequired\n\t}\n\n\tif runConfig.GoVersion == \"\" {\n\t\trunConfig.GoVersion = detectGoVersion()\n\t}\n\n\t// Run pre-flight checks\n\tif runConfig.Verbose {\n\t\tlog.Printf(\"Running pre-flight system checks...\")\n\t}\n\n\terr := runDoctorCheck(env.Context())\n\tif err != nil {\n\t\treturn fmt.Errorf(\"pre-flight checks failed: %w\", err)\n\t}\n\n\tif runConfig.Verbose {\n\t\tlog.Printf(\"Running test: %s\", runConfig.TestPattern)\n\t\tlog.Printf(\"Go version: %s\", runConfig.GoVersion)\n\t\tlog.Printf(\"Timeout: %s\", runConfig.Timeout)\n\t\tlog.Printf(\"Use PostgreSQL: %t\", runConfig.UsePostgres)\n\t}\n\n\treturn runTestContainer(env.Context(), &runConfig)\n}\n\n// detectGoVersion reads the Go version from go.mod file.\nfunc detectGoVersion() string {\n\tcontent, err := os.ReadFile(\"go.mod\")\n\tif err != nil {\n\t\tcontent, err = os.ReadFile(filepath.Join(\"..\", \"..\", \"go.mod\"))\n\t\tif err != nil {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/hi/run.go#L37-L73","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `go run ./cmd/hi doctor` directly — its detailed table shows which check failed (the wrapper hides it behind 'see details above')","Start/repair Docker until `docker info` succeeds","Enter the nix dev shell (`nix develop`) and run from the repository root","Re-run `go run ./cmd/hi run \"TestName\"` once doctor passes"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"go run ./cmd/hi doctor >/dev/null 2>&1 || { echo 'fix environment first'; exit 1; }\ngo run ./cmd/hi run \"TestName\"","typeGuard":null,"tryCatchPattern":"if err := runTest(env.Context()); err != nil {\n    var pre *PreFlightError // or errors.Is against ErrSystemChecksFailed\n    if errors.Is(err, ErrSystemChecksFailed) {\n        // do not retry the test; repair the environment (docker, PATH, repo root)\n    }\n}","preventionTips":["Gate CI jobs on `hi doctor` exit status before running tests","Start Docker before invoking `hi run` in scripts","Run from the repository root inside nix develop"],"tags":["hi-runner","pre-flight","docker","integration-tests"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}