juanfont/headscale · error

running pre-built headscale container %q: %w

Error message

running pre-built headscale container %q: %w

What it means

Returned when pool.RunWithOptions fails for a pre-built headscale image (set via the prebuilt-image option: repository/tag parsed from prebuiltImage). This path skips the local Docker build and runs an already-built image; failure means the image could not be pulled or the container could not be created.

Source

Thrown at integration/hsic/hsic.go:533

	if prebuiltImage != "" {
		log.Printf("Using pre-built headscale image: %s", prebuiltImage) //nolint:gosec // G706: integration-only log of trusted env value
		// Parse image into repository and tag
		repo, tag, ok := strings.Cut(prebuiltImage, ":")
		if !ok {
			return nil, errInvalidHeadscaleImageFormat
		}

		runOptions.Repository = repo
		runOptions.Tag = tag

		container, err = pool.RunWithOptions(
			runOptions,
			dockertestutil.DockerRestartPolicy,
			dockertestutil.DockerAllowLocalIPv6,
			dockertestutil.DockerAllowNetworkAdministration,
		)
		if err != nil {
			return nil, fmt.Errorf("running pre-built headscale container %q: %w", prebuiltImage, err)
		}
	} else if util.IsCI() {
		return nil, errHeadscaleImageRequiredInCI
	} else {
		container, err = pool.BuildAndRunWithBuildOptions(
			headscaleBuildOptions,
			runOptions,
			dockertestutil.DockerRestartPolicy,
			dockertestutil.DockerAllowLocalIPv6,
			dockertestutil.DockerAllowNetworkAdministration,
		)
		if err != nil {
			// Try to get more detailed build output
			log.Printf("Docker build/run failed, attempting to get detailed output...")

			buildOutput, buildErr := dockertestutil.RunDockerBuildForDiagnostics(dockerContextPath, IntegrationTestDockerFileName)

			// Show the last 100 lines of build output to avoid overwhelming the logs

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify the image exists: docker pull <repo:tag> on the same host
2. Check the prebuiltImage string parses into the expected repository and tag (see repo/tag assignment just above)
3. Ensure registry credentials are configured (docker login) for private registries
4. Locally, omit the prebuilt option to fall back to BuildAndRunWithBuildOptions

// Verify the prebuilt image exists locally before running
if _, err := exec.Command("docker", "image", "inspect", prebuiltImage).Output(); err != nil {
    return nil, fmt.Errorf("prebuilt image %q not present; build or pull it first", prebuiltImage)
}

When it happens

Trigger: Passing WithPrebuiltImage / HEADSCALE_PREBUILT_IMAGE (required in CI when not building) and either the image does not exist in the registry, credentials are missing for a private registry, or Docker daemon rejects the run options (network/IPv6 capabilities).

Common situations: CI job referencing an image that was never pushed; typo'd repo:tag; unauthenticated pull from a private registry; local runner never loaded the image; note that in CI (util.IsCI()) the absence of a prebuilt image yields errHeadscaleImageRequiredInCI instead.

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/c6f9267b7a907d97. Report an issue: GitHub.