juanfont/headscale · error

starting postgres container: %w

Error message

starting postgres container: %w

What it means

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.

Source

Thrown at integration/hsic/hsic.go:436

		pgRunOptions := &dockertest.RunOptions{
			Name:       "postgres-" + hash,
			Repository: pgRepo,
			Tag:        pgTag,
			Networks:   networks,
			Env: []string{
				"POSTGRES_USER=headscale",
				"POSTGRES_PASSWORD=headscale",
				"POSTGRES_DB=headscale",
			},
		}

		// Add integration test labels if running under hi tool
		dockertestutil.DockerAddIntegrationLabels(pgRunOptions, "postgres")

		pg, err := pool.RunWithOptions(pgRunOptions)
		if err != nil {
			return nil, fmt.Errorf("starting postgres container: %w", err)
		}

		hsic.pgContainer = pg
	}

	env := []string{
		"HEADSCALE_DEBUG_PROFILING_ENABLED=1",
		"HEADSCALE_DEBUG_PROFILING_PATH=/tmp/profile",
		"HEADSCALE_DEBUG_DUMP_MAPRESPONSE_PATH=/tmp/mapresponses",
		"HEADSCALE_DEBUG_DEADLOCK=1",
		"HEADSCALE_DEBUG_DEADLOCK_TIMEOUT=5s",
		"HEADSCALE_DEBUG_HIGH_CARDINALITY_METRICS=1",
		"HEADSCALE_DEBUG_DUMP_CONFIG=1",
	}
	if hsic.hasTLS() {
		hsic.env["HEADSCALE_TLS_CERT_PATH"] = tlsCertPath
		hsic.env["HEADSCALE_TLS_KEY_PATH"] = tlsKeyPath
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `go run ./cmd/hi doctor` to verify Docker connectivity and pre-pulled images
2. Pre-pull the postgres image used in hsic.go (docker pull postgres:<tag>) to avoid registry rate limits
3. Check DOCKER_HOST env and that the user has docker daemon access
4. Reduce parallel containers or increase Docker resources

// Pre-pull and verify Docker connectivity before tests
if err := dockerPullIfMissing("postgres:16"); err != nil { t.Skipf("docker unavailable: %v", err) }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w
• writing TLS certificate to container: %w
• writing TLS key to container: %w
• DERPer is not ready: %w

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