juanfont/headscale · error

listing original clients: %w

Error message

listing original clients: %w

What it means

Returned by Scenario.AddAndLoginClient when s.ListTailscaleClients(username) fails while snapshotting the pre-existing client list. It wraps the underlying listing error; the add-and-login flow aborts before creating any node.

Source

Thrown at integration/helpers.go:1154

// AddAndLoginClient adds a new tailscale client to a user and logs it in.
// This combines the common pattern of:
// 1. Creating a new node
// 2. Finding the new node in the client list
// 3. Getting the user to create a preauth key
// 4. Logging in the new node.
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 {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Check that the user's existing client containers are running before adding another
2. Inspect the wrapped listing error and container states (docker ps) for the failing client
3. Re-run the scenario if Docker was transiently unhealthy; prune leftover state first

// ensure the user's clients are up before adding another
clients, err := s.ListTailscaleClients(username)
if err != nil {
    return fmt.Errorf("precondition failed, cannot list clients: %w", err)
}
for _, c := range clients {
    if !c.IsRunning() { // or equivalent status check
        return fmt.Errorf("existing client unhealthy")
    }
}

c, err := s.AddAndLoginClient(t, user, ver, h, opts...)
if err != nil {
    if strings.Contains(err.Error(), "listing original clients") {
        // inspect Docker health of that user's containers before retrying
    }
    return err
}

When it happens

Trigger: Calling AddAndLoginClient when listing clients for the user fails — user's containers unreachable, Docker exec errors, or the headscale control connection used for listing is broken.

Common situations: Prior test steps left client containers stopped/unhealthy; Docker daemon flakiness under parallel suites; the username's network was torn down by an earlier cleanup.

Related errors

• creating tailscale node: %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/92bf2611c350ac84. Report an issue: GitHub.