juanfont/headscale · error

finding headscale: %w

Error message

finding headscale: %w

What it means

The Scenario has no headscale container available to service the operation; the loop over candidate headscale instances found none, so the helper returns `fmt.Errorf("finding headscale: %w", errNoHeadscaleAvailable)`. It means `s.headscale` (or the pool of instances) was never populated or has been torn down.

Source

Thrown at integration/scenario.go:1371

	key := keySep[1]
	key = strings.SplitN(key, " ", 2)[0]
	log.Printf("registering node %s", key)

	if headscale, err := s.Headscale(); err == nil { //nolint:noinlineerr
		_, err = headscale.Execute(
			[]string{"headscale", "auth", "register", "--user", userStr, "--auth-id", key},
		)
		if err != nil {
			log.Printf("registering node: %s", err)

			return err
		}

		return nil
	}

	return fmt.Errorf("finding headscale: %w", errNoHeadscaleAvailable)
}

type LoggingRoundTripper struct {
	Hostname string
}

func (t LoggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
	noTls := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, // nolint
	}

	resp, err := noTls.RoundTrip(req)
	if err != nil {
		return nil, err
	}

	//nolint:gosec // G706: integration-only log of trusted scenario state
	log.Printf(`

View on GitHub (pinned to 565fd254d0)

Solutions

1. Ensure `CreateHeadscale`/`Start` is called and its error checked before any register/status helper.
2. If startup failed, look at that earlier error — this one is only a downstream symptom.
3. Guard test setup with `require.NoError` on headscale creation so failures abort before reaching here.

// Fail fast before using the scenario.
if s.Headscale() == nil { // or equivalent accessor
    t.Fatal("no headscale available; call CreateHeadscale first")
}

When it happens

Trigger: Calling a Scenario method that needs a control server (e.g. runHeadscaleRegister's CLI path) before `Scenario.CreateHeadscale`/`Start` succeeded, or after shutdown removed the container.

Common situations: Test helper ordering mistake — registering a node before the headscale container is started; a prior startup failed silently and the test continued; teardown ran early.

Related errors

• %s confirm form: unterminated action attribute
• test failed
• unexpected end of container wait
• no docker context found
• system checks failed

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