juanfont/headscale · error

no network named: %s

Error message

no network named: %s

What it means

Returned by Scenario.Network(name) when no Docker network was registered in the scenario under the given (prefix-normalised) name. It is a sentinel-style lookup failure, marked nolint:err113 because it is a dynamic (non-wrapped) error created at the call site.

Source

Thrown at integration/scenario.go:326

	}

	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 {
		return nil, fmt.Errorf("no network named: %s", name) //nolint:err113
	}

	return net, nil
}

func (s *Scenario) SubnetOfNetwork(name string) (*netip.Prefix, error) {
	net, ok := s.networks[s.prefixedNetworkName(name)]
	if !ok {
		return nil, fmt.Errorf("no network named: %s", name) //nolint:err113
	}

	if len(net.Network.IPAM.Config) == 0 {
		return nil, fmt.Errorf("no IPAM config found in network: %s", name) //nolint:err113
	}

	pref, err := netip.ParsePrefix(net.Network.IPAM.Config[0].Subnet)
	if err != nil {
		return nil, err

View on GitHub (pinned to 565fd254d0)

Solutions

1. Ensure AddNetwork(name) succeeded before any Network(name) call in the test flow
2. Compare the exact name string used for creation and lookup (names are stored prefixed via prefixedNetworkName)
3. Capture the *dockertest.Network returned by AddNetwork and reuse it instead of re-looking it up by name

Example fix

// before
net, err := scenario.Network("mynet")

// after: keep the handle from creation
net, err := scenario.AddNetwork("mynet")
if err != nil {
    t.Fatalf("creating network: %s", err)
}

func hasNetwork(s *integration.Scenario, name string) bool {
    _, err := s.Network(name)
    return err == nil
}

net, err := scenario.Network(name)
if err != nil {
    t.Fatalf("network %q missing — was AddNetwork called? %v", name, err)
}

When it happens

Trigger: Calling s.Network(name) before s.AddNetwork(name), or with a name that was never added; also when the lookup key's scenario prefix does not match the name used at creation.

Common situations: Test helper fetches a network by string that differs from the one used in AddNetwork (typo, extra prefix); calling Network after Shutdown cleared the map; copy-paste between scenarios with different network names.

Related errors

• DERPer is not ready: %w
• creating or getting network: %w
• adding test suite container to network: %w
• 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/69b12bca062987c8. Report an issue: GitHub.