juanfont/headscale · error

creating tailscale node (version: %s): %w

Error message

creating tailscale node (version: %s): %w

What it means

Returned by Scenario.CreateTailscaleNode when s.Headscale() fails: the node cannot be created because the control server's TLS cert and hostname (needed to configure the tailscale client container) are unavailable. Wraps the headscale availability error, annotated with the requested client version.

Source

Thrown at integration/scenario.go:602

			Clients: make(map[string]TailscaleClient),
		}
		s.mu.Unlock()

		return u, nil
	}

	return nil, fmt.Errorf("creating user: %w", errNoHeadscaleAvailable)
}

/// Client related stuff

func (s *Scenario) CreateTailscaleNode(
	version string,
	opts ...tsic.Option,
) (TailscaleClient, error) {
	headscale, err := s.Headscale()
	if err != nil {
		return nil, fmt.Errorf("creating tailscale node (version: %s): %w", version, err)
	}

	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...,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Fix headscale availability first: inspect scenario.Headscale() error and control container logs
2. Ensure node creation happens while the scenario is live
3. Run the environment doctor and retry via `go run ./cmd/hi run`

if _, err := scenario.Headscale(); err != nil {
    t.Fatalf("control server unavailable, cannot create node: %v", err)
}

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

When it happens

Trigger: Calling CreateTailscaleNode(version, opts...) when the headscale container never started or was torn down, so GetCert/GetHostname cannot be sourced.

Common situations: Earlier headscale startup failure; test creating nodes after Shutdown; the version string pointing to an unavailable client image is NOT this error's cause (that fails later in tsic.New).

Related errors

• node name is not unique
• node not found
• route is not available on node
• failed to convert node interface
• node not found

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