juanfont/headscale · error

creating tailscale node: %w

Error message

creating tailscale node: %w

What it means

Returned by Scenario.AddAndLoginClient when s.CreateTailscaleNodesInUser fails to create and start the new tailscale node container. It wraps the underlying container-creation error; the subsequent 'wait for it to appear' phase never runs.

Source

Thrown at integration/helpers.go:1160

func (s *Scenario) AddAndLoginClient(
	t *testing.T,
	username string,
	version string,
	headscale ControlServer,
	tsOpts ...tsic.Option,
) (TailscaleClient, error) {
	t.Helper()

	// Get the original client list
	originalClients, err := s.ListTailscaleClients(username)
	if err != nil {
		return nil, fmt.Errorf("listing original clients: %w", err)
	}

	// Create the new node
	err = s.CreateTailscaleNodesInUser(username, version, 1, tsOpts...)
	if err != nil {
		return nil, fmt.Errorf("creating tailscale node: %w", err)
	}

	// Wait for the new node to appear in the client list
	var newClient TailscaleClient

	_, err = backoff.Retry(t.Context(), func() (struct{}, error) {
		updatedClients, err := s.ListTailscaleClients(username)
		if err != nil {
			return struct{}{}, fmt.Errorf("listing updated clients: %w", err)
		}

		if len(updatedClients) != len(originalClients)+1 {
			return struct{}{}, fmt.Errorf("expected %d clients, got %d", len(originalClients)+1, len(updatedClients)) //nolint:err113
		}

		newClient, err = FindNewClient(originalClients, updatedClients)
		if err != nil {
			return struct{}{}, fmt.Errorf("finding new client: %w", err)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify the tailscale image for the requested version exists locally or is pullable
2. Clean up Docker leftovers (networks, stopped containers) from earlier failed runs
3. Free host resources or lower test parallelism, then retry the scenario

// preflight: image exists locally or is pullable
func imageAvailable(ref string) bool {
    // docker image inspect ref || docker pull ref
    return true // implement with your docker client of choice
}

c, err := s.AddAndLoginClient(t, user, ver, h, opts...)
if err != nil && strings.Contains(err.Error(), "creating tailscale node") {
    // prune leftovers, verify image for ver, retry once
}

When it happens

Trigger: Calling AddAndLoginClient with a tailscale version whose image cannot be pulled/built, or Docker failing to start the container (resource limits, name/network conflicts).

Common situations: Testing an unreleased tailscale version whose image isn't built locally; Docker network/subnet exhaustion from prior runs; CI disk pressure preventing container start.

Related errors

• listing original clients: %w
• 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

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