What causes "network does not exist: %s" in juanfont/headscale?

Create the network through the Scenario's network helper so it is registered with the prefixed key.

network does not exist: %s

Error message

network does not exist: %s

What it means

`Webservice(s, networkName)` looks up `s.networks[s.prefixedNetworkName(networkName)]` and the key is absent — the helper only attaches containers to networks the Scenario itself created, and the requested name (after prefixing) does not match any of them.

Source

Thrown at integration/scenario.go:1708

	return nil
}

type extraServiceFunc func(*Scenario, string) (*dockertest.Resource, error)

func Webservice(s *Scenario, networkName string) (*dockertest.Resource, error) {
	// port, err := dockertestutil.RandomFreeHostPort()
	// if err != nil {
	// 	log.Fatalf("finding open port: %s", err)
	// }
	// portNotation := fmt.Sprintf("%d/tcp", port)
	hash := rands.HexString(hsicOIDCMockHashLength)

	hostname := "hs-webservice-" + hash

	network, ok := s.networks[s.prefixedNetworkName(networkName)]
	if !ok {
		return nil, fmt.Errorf("network does not exist: %s", networkName) //nolint:err113
	}

	webOpts := &dockertest.RunOptions{
		Name: hostname,
		Cmd:  []string{"/bin/sh", "-c", "cd / ; python3 -m http.server --bind :: 80"},
		// ExposedPorts: []string{portNotation},
		// PortBindings: map[docker.Port][]docker.PortBinding{
		// 	docker.Port(portNotation): {{HostPort: strconv.Itoa(port)}},
		// },
		Networks: []*dockertest.Network{network},
		Env:      []string{},
	}

	// Add integration test labels if running under hi tool
	dockertestutil.DockerAddIntegrationLabels(webOpts, "web")

	webBOpts := &dockertest.BuildOptions{
		Dockerfile: hsic.IntegrationTestDockerFileName,

View on GitHub (pinned to 565fd254d0)

Solutions

Create the network through the Scenario's network helper so it is registered with the prefixed key.
Print the keys of `s.networks` and use one of those exact (prefixed or correct raw) names.
Check call ordering: network creation must precede Webservice.

Defensive patterns

Strategy: validation

Validate before calling

// Check network existence before calling Webservice.
found := false
for name := range s.networks {
    if name == s.prefixedNetworkName(networkName) { found = true }
}
if !found {
    t.Fatalf("network %q missing; create it via the scenario first", networkName)
}

Prevention

Always create Docker networks through the Scenario helpers.
Create networks before any container that references them.
Print s.networks keys in test failures to surface prefix mismatches.

When it happens

Trigger: Passing a network name that was never created via the Scenario, or an unprefixed name when the scenario store keys are prefixed, or a name created after the webservice call.

Common situations: Test creates networks manually instead of through the Scenario helper; name typo or prefix mismatch; calling Webservice before network creation.

Related errors

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