juanfont/headscale · error

creating tailscale node: %w

Error message

creating tailscale node: %w

What it means

Returned by Scenario.CreateTailscaleNode when tsic.New fails to create the tailscale client container for the requested version. This is the Docker-side creation of the node: image resolution/pull, container creation, or startup wrapping.

Source

Thrown at integration/scenario.go:623

	cert := headscale.GetCert()
	hostname := headscale.GetHostname()

	s.mu.Lock()
	defer s.mu.Unlock()

	opts = append(
		opts,
		tsic.WithCACert(cert),
		tsic.WithHeadscaleName(hostname),
	)

	tsClient, err := tsic.New(
		s.pool,
		version,
		opts...,
	)
	if err != nil {
		return nil, fmt.Errorf(
			"creating tailscale node: %w",
			err,
		)
	}

	err = tsClient.WaitForNeedsLogin(integrationutil.PeerSyncTimeout())
	if err != nil {
		return nil, fmt.Errorf(
			"waiting for tailscaled (%s) to need login: %w",
			tsClient.Hostname(),
			err,
		)
	}

	return tsClient, nil
}

// CreateTailscaleNodesInUser creates and adds a new [TailscaleClient] to a

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify the version string matches an available image (`docker images | grep tailscale`) or pull it
2. Check the wrapped dockertest error for pull/create specifics
3. Reduce concurrent nodes or free Docker resources (disk, memory) if creation fails late in a run
4. Clean stale containers from crashed runs with `go run ./cmd/hi cleanup`

// Ensure the client image exists before the scenario needs it
if err := pullTailscaleImage(version); err != nil { // docker pull tailscale/tailscale:<version>
    t.Fatalf("client image %s unavailable: %v", version, err)
}

node, err := scenario.CreateTailscaleNode(version, opts...)
if err != nil {
    t.Fatalf("creating tailscale node (%s): %v", version, err)
}

When it happens

Trigger: Calling CreateTailscaleNode with a version whose container image is unavailable locally/registry, or when Docker cannot create/start the client container (resource limits, bad option).

Common situations: Using an unpulled tailscale image tag (e.g. a new version not present locally); typo'd version string; Docker daemon resource exhaustion after many nodes; custom tsic.Option with invalid values.

Related errors

• reading container logs: %w
• creating headscale container: %w
• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w
• writing TLS certificate to container: %w

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