{"record":{"id":"00242694f54fb4b3","repo":"juanfont/headscale","slug":"creating-headscale-container-w","errorCode":null,"errorMessage":"creating headscale container: %w","messagePattern":"creating headscale container: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"integration/scenario.go","lineNumber":482,"sourceCode":"// Headscale returns a [ControlServer] instance based on hsic ([hsic.HeadscaleInContainer]).\n// If the [Scenario] already has an instance, the pointer to the running container\n// will be return, otherwise a new instance will be created.\n// TODO(kradalby): make port and headscale configurable, multiple instances support?\nfunc (s *Scenario) Headscale(opts ...hsic.Option) (ControlServer, error) {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\n\tif headscale, ok := s.controlServers.Load(\"headscale\"); ok {\n\t\treturn headscale, nil\n\t}\n\n\tif usePostgresForTest {\n\t\topts = append(opts, hsic.WithPostgres())\n\t}\n\n\theadscale, err := hsic.New(s.pool, s.Networks(), opts...)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"creating headscale container: %w\", err)\n\t}\n\n\terr = headscale.WaitForRunning()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"reaching headscale container: %w\", err)\n\t}\n\n\ts.controlServers.Store(\"headscale\", headscale)\n\n\treturn headscale, nil\n}\n\n// Pool returns the [dockertest.Pool] for the scenario.\nfunc (s *Scenario) Pool() *dockertest.Pool {\n\treturn s.pool\n}\n\n// GetOrCreateUser gets or creates a user in the [Scenario].","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/scenario.go#L464-L500","documentation":"Returned by Scenario.Headscale when hsic.New fails to build and start the headscale control-server container. It wraps container creation, image pull, config mounting, and container start errors from dockertest.","triggerScenarios":"First call to s.Headscale() (or any Scenario helper that transitively needs a control server) when the headscale image cannot be pulled/built, config generation fails, or the container exits during startup.","commonSituations":"Missing or stale locally built headscale image (hsic.New typically uses a locally built image; run make build / the documented docker build first); insufficient Docker resources; a bad hsic.Option (invalid config values, missing env); port conflicts on the host.","solutions":["Build the headscale image first: `make build` followed by the documented docker image build step in integration/README.md","Run `go run ./cmd/hi doctor` to validate the Docker environment before tests","Inspect the wrapped error and `docker logs` of the half-created container for startup failures (bad config, bad option)","Disable/comment custom hsic.Options added by the test to isolate the failing option"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if err := integration.CheckDockerEnvironment(); err != nil { // hi doctor equivalent\n    t.Skip(\"docker environment not ready\")\n}","typeGuard":null,"tryCatchPattern":"headscale, err := scenario.Headscale()\nif err != nil {\n    // environment-level failure: abort, do not retry blindly\n    t.Fatalf(\"control server unavailable: %v\", err)\n}","preventionTips":["Build the headscale image before the suite","Run `hi doctor` first","Keep test-provided hsic.Options minimal and validated"],"tags":["docker","headscale","integration-test","container"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}