juanfont/headscale · error

creating or getting network: %w

Error message

creating or getting network: %w

What it means

Returned by Scenario.AddNetwork/AddNetworkWithSubnet when dockertestutil.GetFirstOrCreateNetworkWithSubnet fails to list existing Docker networks or to create the requested network. It wraps Docker daemon errors from network creation/lookup.

Source

Thrown at integration/scenario.go:293

		}

		err = s.runMockOIDC(ttl, spec.OIDCUsers)
		if err != nil {
			return nil, err
		}
	}

	return s, nil
}

func (s *Scenario) AddNetwork(name string) (*dockertest.Network, error) {
	return s.AddNetworkWithSubnet(name, "")
}

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)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `docker network ls` and prune leftover headscale test networks, or run `go run ./cmd/hi cleanup`
2. Verify the subnet argument is a valid CIDR (e.g. 172.10.0.0/24) and does not overlap existing networks
3. Confirm the Docker daemon is running and the user has access to /var/run/docker.sock
4. Check whether another concurrent integration run holds conflicting networks (run IDs should isolate them)

net, err := scenario.AddNetworkWithSubnet(name, subnet)
if err != nil {
    t.Fatalf("network setup failed: %v", err) // environment error; abort the test

When it happens

Trigger: Calling s.AddNetwork(name) or s.AddNetworkWithSubnet(name, subnet) when the Docker daemon is unreachable, the subnet string is invalid/overlaps an existing network, or network creation hits a daemon limit.

Common situations: Invalid subnet passed to AddNetworkWithSubnet (not CIDR format, or colliding with another test network's range); too many leftover networks from earlier runs exhausting Docker's address pool; Docker socket permission problems.

Related errors

• DERPer is not ready: %w
• adding test suite container to 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/9a9dc84b1693508c. Report an issue: GitHub.