juanfont/headscale · error

adding test suite container to network: %w

Error message

adding test suite container to network: %w

What it means

Returned by Scenario.AddNetworkWithSubnet when dockertestutil.AddContainerToNetwork fails to attach the test-suite container (headscale-test-suite[-runID]) to the newly created network. The suite container must be attached so test-code HTTP readiness checks can reach containers on per-test networks.

Source

Thrown at integration/scenario.go:307

func (s *Scenario) AddNetworkWithSubnet(name, subnet string) (*dockertest.Network, error) {
	network, err := dockertestutil.GetFirstOrCreateNetworkWithSubnet(s.pool, name, subnet)
	if err != nil {
		return nil, fmt.Errorf("creating or getting network: %w", err)
	}

	// We run the test suite in a docker container that calls a couple of endpoints for
	// readiness checks, this ensures that we can run the tests with individual networks
	// and have the client reach the different containers.
	// The container name includes the run ID to support multiple concurrent test runs.
	testSuiteName := "headscale-test-suite"
	if runID := dockertestutil.GetIntegrationRunID(); runID != "" {
		testSuiteName = "headscale-test-suite-" + runID
	}

	err = dockertestutil.AddContainerToNetwork(s.pool, network, testSuiteName)
	if err != nil {
		return nil, fmt.Errorf("adding test suite container to network: %w", err)
	}

	mak.Set(&s.networks, name, network)

	return network, nil
}

func (s *Scenario) Networks() []*dockertest.Network {
	if len(s.networks) == 0 {
		panic("Scenario.Networks called with empty network list")
	}

	return xmaps.Values(s.networks)
}

func (s *Scenario) Network(name string) (*dockertest.Network, error) {
	net, ok := s.networks[s.prefixedNetworkName(name)]
	if !ok {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run integration tests via the documented runner: `go run ./cmd/hi run "TestName"` which creates the test-suite container
2. Run `go run ./cmd/hi doctor` to verify the environment is healthy before running tests
3. If a run was interrupted, clean stale state with `go run ./cmd/hi cleanup` and retry

if _, err := scenario.AddNetwork(name); err != nil {
    t.Fatalf("network setup failed: %v", err)
}

When it happens

Trigger: Occurs when the headscale-test-suite container does not exist (suite not running under cmd/hi), has been removed mid-run, or the Docker API call to connect it to the network fails.

Common situations: Running integration tests with `go test ./integration/...` directly instead of through the hi runner that creates the suite container; a previous run's cleanup removed the suite container while a test was adding a network; concurrent runs with colliding run IDs.

Related errors

• DERPer is not ready: %w
• creating or getting network: %w
• no network named: %s
• no IPAM config found in network: %s
• ensuring image availability: %w

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