vxcontrol/pentagi · error

failed to create network %s: %w

Error message

failed to create network %s: %w

What it means

Returned when creating the Docker bridge network for a flow fails via cli.NetworkCreate. The network name is embedded in the message and the daemon error is wrapped so the root cause remains inspectable.

Source

Thrown at backend/pkg/docker/client.go:1327

}

// ensureDockerNetwork verifies that a docker network with the given name exists;
// if it does not, it attempts to create it.
// Special case: "host" network mode is built-in and doesn't need creation.
func ensureDockerNetwork(ctx context.Context, cli *client.Client, name string) error {
	if name == "" || name == "host" {
		return nil
	}

	if _, err := cli.NetworkInspect(ctx, name, client.NetworkInspectOptions{}); err == nil {
		return nil
	}

	_, err := cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
		Driver: "bridge",
	})
	if err != nil {
		return fmt.Errorf("failed to create network %s: %w", name, err)
	}

	return nil
}

View on GitHub (pinned to ea665308ba)

Solutions

1. Check if a network with the same name exists (`docker network ls`) and remove the stale one (`docker network rm`)
2. Free address space: remove unused networks (`docker network prune`) or configure larger default-address-pools in daemon.json
3. Restart the Docker daemon to rebuild bridge/iptables state
4. Check the wrapped daemon error for the precise cause (conflict vs pool vs driver)

Example fix

// before
_, err := cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{Driver: "bridge"})
// after
_, err := cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{Driver: "bridge"})
if err != nil && strings.Contains(err.Error(), "already exists") {
    return nil // or inspect/reuse the existing network
}

// pre-check
docker network ls --format '{{.Name}}' | grep -qx <name> && docker network rm <name>

func isNetworkCreateError(err error) bool { return strings.Contains(err.Error(), "failed to create network") }

if err := dc.ensureNetwork(ctx, name); err != nil {
    if strings.Contains(err.Error(), "already exists") {
        // reuse existing network
    } else {
        log.WithError(err).Error("network create failed")
    }
}

When it happens

Trigger: NetworkCreate fails because a network with the same name already exists with conflicting settings, the address pool is exhausted, or the daemon's bridge/networking subsystem is broken.

Common situations: Leftover network from a previous crashed run; default Docker address pool (default 31 /16 networks) exhausted by many flows/compose stacks; kernel/iptables issues after host updates; daemon misconfiguration of the bridge driver.

Related errors

• failed to ensure docker network %s: %w
• failed to pull default image '%s': %w
• truncated exec stream: %w
• failed to pull image: %w
• image download stream processing failed: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/b060bcfc5b9a2fbf. Report an issue: GitHub.