{"record":{"id":"2c7a17bd3afb787a","repo":"juanfont/headscale","slug":"starting-postgres-container-w","errorCode":null,"errorMessage":"starting postgres container: %w","messagePattern":"starting postgres container: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":436,"sourceCode":"\n\t\tpgRunOptions := &dockertest.RunOptions{\n\t\t\tName:       \"postgres-\" + hash,\n\t\t\tRepository: pgRepo,\n\t\t\tTag:        pgTag,\n\t\t\tNetworks:   networks,\n\t\t\tEnv: []string{\n\t\t\t\t\"POSTGRES_USER=headscale\",\n\t\t\t\t\"POSTGRES_PASSWORD=headscale\",\n\t\t\t\t\"POSTGRES_DB=headscale\",\n\t\t\t},\n\t\t}\n\n\t\t// Add integration test labels if running under hi tool\n\t\tdockertestutil.DockerAddIntegrationLabels(pgRunOptions, \"postgres\")\n\n\t\tpg, err := pool.RunWithOptions(pgRunOptions)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"starting postgres container: %w\", err)\n\t\t}\n\n\t\thsic.pgContainer = pg\n\t}\n\n\tenv := []string{\n\t\t\"HEADSCALE_DEBUG_PROFILING_ENABLED=1\",\n\t\t\"HEADSCALE_DEBUG_PROFILING_PATH=/tmp/profile\",\n\t\t\"HEADSCALE_DEBUG_DUMP_MAPRESPONSE_PATH=/tmp/mapresponses\",\n\t\t\"HEADSCALE_DEBUG_DEADLOCK=1\",\n\t\t\"HEADSCALE_DEBUG_DEADLOCK_TIMEOUT=5s\",\n\t\t\"HEADSCALE_DEBUG_HIGH_CARDINALITY_METRICS=1\",\n\t\t\"HEADSCALE_DEBUG_DUMP_CONFIG=1\",\n\t}\n\tif hsic.hasTLS() {\n\t\thsic.env[\"HEADSCALE_TLS_CERT_PATH\"] = tlsCertPath\n\t\thsic.env[\"HEADSCALE_TLS_KEY_PATH\"] = tlsKeyPath\n\t}","sourceCodeStart":418,"sourceCodeEnd":454,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L418-L454","documentation":"Thrown when pool.RunWithOptions(pgRunOptions) fails to start the sidecar PostgreSQL container (POSTGRES_USER/PASSWORD/DB all 'headscale') used when a test requests a Postgres backend. dockertest delegates to the Docker daemon; failure means image pull failure, daemon unavailability, or resource limits.","triggerScenarios":"Constructing HeadscaleInContainer with WithPostgres option; dockertest tries to pull the postgres image and run it. Fails when Docker is not reachable, the registry is unreachable/rate-limited, the image tag is missing locally, or the daemon is out of resources/ports.","commonSituations":"No DOCKER_HOST / daemon not running; Docker Hub rate limiting in CI; pinned postgres image not pre-pulled on offline runners; concurrent tests exhausting container limits.","solutions":["Run `go run ./cmd/hi doctor` to verify Docker connectivity and pre-pulled images","Pre-pull the postgres image used in hsic.go (docker pull postgres:<tag>) to avoid registry rate limits","Check DOCKER_HOST env and that the user has docker daemon access","Reduce parallel containers or increase Docker resources"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Pre-pull and verify Docker connectivity before tests\nif err := dockerPullIfMissing(\"postgres:16\"); err != nil { t.Skipf(\"docker unavailable: %v\", err) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `go run ./cmd/hi doctor` before Postgres-backed suites","Pre-pull the postgres image on CI runners to dodge Hub rate limits","Confirm DOCKER_HOST points at a reachable daemon"],"tags":["integration-test","docker","postgres","dockertest"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}