juanfont/headscale · error

running pre-built tailscale container %q: %w

Error message

running pre-built tailscale container %q: %w

What it means

dockertest's `RunWithOptions` failed while starting a container from a pre-built tailscale image (`HEADSCALE_INTEGRATION_TAILSCALE_IMAGE`, format repository:tag). The error names the image and wraps dockertest's failure: image not found locally/remotely, tag mismatch, name conflict, or Docker daemon issues.

Source

Thrown at integration/tsic/tsic.go:461

			// Parse image into repository and tag
			repo, tag, ok := strings.Cut(prebuiltImage, ":")
			if !ok {
				return nil, errInvalidTailscaleImageFormat
			}

			tailscaleOptions.Repository = repo
			tailscaleOptions.Tag = tag

			container, err = pool.RunWithOptions(
				tailscaleOptions,
				dockertestutil.DockerRestartPolicy,
				dockertestutil.DockerAllowLocalIPv6,
				dockertestutil.DockerAllowNetworkAdministration,
				dockertestutil.DockerMemoryLimit,
			)
			if err != nil {
				return nil, fmt.Errorf("running pre-built tailscale container %q: %w", prebuiltImage, err)
			}
		} else if util.IsCI() && !hasBuildTags {
			// In CI, we require a pre-built image unless custom build tags are needed
			return nil, errTailscaleImageRequiredInCI
		} else {
			buildOptions := &dockertest.BuildOptions{
				Dockerfile: "Dockerfile.tailscale-HEAD",
				ContextDir: dockerContextPath,
				BuildArgs:  []docker.BuildArg{},
			}

			buildTags := strings.Join(tsic.buildConfig.tags, ",")
			if len(buildTags) > 0 {
				buildOptions.BuildArgs = append(
					buildOptions.BuildArgs,
					docker.BuildArg{
						Name:  "BUILD_TAGS",
						Value: buildTags,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify the image exists: `docker image inspect <repo:tag>`; pull or rebuild it if missing.
2. Remove conflicting containers from prior runs (`docker rm -f` or the repo cleanup command).
3. In CI, confirm the image is built/pushed before the job step that runs integration tests.
4. Check Docker daemon health and disk space.

// Pre-flight the prebuilt image before tests.
if img := os.Getenv("HEADSCALE_INTEGRATION_TAILSCALE_IMAGE"); img != "" {
    if err := exec.Command("docker", "image", "inspect", img).Run(); err != nil {
        log.Fatalf("prebuilt image %s missing; pull or build it first", img)
    }
}

When it happens

Trigger: Running a client with a prebuilt image configured when the image does not exist locally and cannot be pulled, a stale container with the same generated name exists, or the Docker daemon is out of resources.

Common situations: HEADSCALE_INTEGRATION_TAILSCALE_IMAGE points at an untagged/unpushed image; local cache pruned; leftover container from a crashed run; CI registry auth missing for a private image.

Related errors

• %s failed to fetch tailscale status: %w
• no network set, called from: %s
• %s could not start tailscale container (version: %s): %w Do
• creating tailscale node: %w
• %s sending confirm request: %w

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