vxcontrol/pentagi · error

failed to ensure docker network %s: %w

Error message

failed to ensure docker network %s: %w

What it means

When cfg.DockerNetwork names a network, NewDockerClient calls ensureDockerNetwork to create or validate it on the daemon before the client is returned. If the daemon call fails (network can't be created or inspected), the error is wrapped as "failed to ensure docker network %s: %w" with the network name interpolated. This aborts startup because per-flow containers would otherwise fail to attach.

Source

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

	defImage := strings.ToLower(cfg.DockerDefaultImage)
	if defImage == "" {
		defImage = defaultImage
	}

	dataDir, err := filepath.Abs(cfg.DataDir)
	if err != nil {
		return nil, fmt.Errorf("failed to get absolute path: %w", err)
	}

	if err := os.MkdirAll(dataDir, 0755); err != nil {
		return nil, fmt.Errorf("failed to create tmp directory: %w", err)
	}

	hostDir := getHostDataDir(ctx, cli, dataDir, cfg.DockerWorkDir)

	// ensure network exists if configured
	if err := ensureDockerNetwork(ctx, cli, netName); err != nil {
		return nil, fmt.Errorf("failed to ensure docker network %s: %w", netName, err)
	}

	logger := logrus.StandardLogger()
	logger.WithFields(logrus.Fields{
		"docker_name":        info.Name,
		"docker_arch":        info.Architecture,
		"docker_version":     info.ServerVersion,
		"client_version":     cli.ClientVersion(),
		"data_dir":           dataDir,
		"host_dir":           hostDir,
		"docker_inside":      inside,
		"docker_socket":      socket,
		"docker_inside_host": cfg.DockerInsideHost,
		"public_ip":          publicIP,
	}).Debug("Docker client initialized")

	return &dockerClient{
		db:             db,

View on GitHub (pinned to ea665308ba)

Solutions

1. Run 'docker network ls' and 'docker network inspect <name>' to see if it exists with conflicting settings; remove or align it (docker network rm <name>).
2. Prune unused networks to free subnets: docker network prune; or extend default-address-pools in daemon.json.
3. Verify DOCKER_NETWORK name spelling and that the target daemon (DOCKER_HOST) is the one that has/should create the network.
4. Create the network manually beforehand: docker network create <name>.
5. Check daemon logs (journalctl -u docker) for the underlying creation failure.

Example fix

// before
DOCKER_NETWORK=pentagi-net  # exists with different driver, create fails
// after
docker network rm pentagi-net  # or: docker network create --driver bridge pentagi-net

name := cfg.DockerNetwork
if name != "" {
    nets, err := cli.NetworkList(ctx, client.NetworkListOptions{})
    if err != nil { return err }
    for _, n := range nets {
        if n.Name == name { /* exists and reusable — OK */ }
    }
    // optionally pre-create: cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{})
}

if _, err := NewDockerClient(ctx, db, cfg); err != nil {
    if strings.Contains(err.Error(), "failed to ensure docker network") {
        log.Fatalf("network %q unusable: %v — inspect/prune docker networks and retry", cfg.DockerNetwork, err)
    }
    return err
}

When it happens

Trigger: ensureDockerNetwork(ctx, cli, netName) fails: network create rejected (invalid name, duplicate with different driver/settings, exhausted default address pool / no free subnets), daemon unreachable, or a user-scoped daemon lacking network management permission.

Common situations: DOCKER_NETWORK set to a name that already exists as a network with incompatible options; Docker default address pool exhausted after many compose networks; typo'd network name with DOCKER_HOST to a remote daemon that lacks it; DinD setups where the inner daemon has no network plugin.

Related errors

• failed to get docker info: %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/20cf4e3b7f43bcd1. Report an issue: GitHub.