{"record":{"id":"20cf4e3b7f43bcd1","repo":"vxcontrol/pentagi","slug":"failed-to-ensure-docker-network-s-w","errorCode":null,"errorMessage":"failed to ensure docker network %s: %w","messagePattern":"failed to ensure docker network (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/docker/client.go","lineNumber":178,"sourceCode":"\tdefImage := strings.ToLower(cfg.DockerDefaultImage)\n\tif defImage == \"\" {\n\t\tdefImage = defaultImage\n\t}\n\n\tdataDir, err := filepath.Abs(cfg.DataDir)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get absolute path: %w\", err)\n\t}\n\n\tif err := os.MkdirAll(dataDir, 0755); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create tmp directory: %w\", err)\n\t}\n\n\thostDir := getHostDataDir(ctx, cli, dataDir, cfg.DockerWorkDir)\n\n\t// ensure network exists if configured\n\tif err := ensureDockerNetwork(ctx, cli, netName); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to ensure docker network %s: %w\", netName, err)\n\t}\n\n\tlogger := logrus.StandardLogger()\n\tlogger.WithFields(logrus.Fields{\n\t\t\"docker_name\":        info.Name,\n\t\t\"docker_arch\":        info.Architecture,\n\t\t\"docker_version\":     info.ServerVersion,\n\t\t\"client_version\":     cli.ClientVersion(),\n\t\t\"data_dir\":           dataDir,\n\t\t\"host_dir\":           hostDir,\n\t\t\"docker_inside\":      inside,\n\t\t\"docker_socket\":      socket,\n\t\t\"docker_inside_host\": cfg.DockerInsideHost,\n\t\t\"public_ip\":          publicIP,\n\t}).Debug(\"Docker client initialized\")\n\n\treturn &dockerClient{\n\t\tdb:             db,","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/docker/client.go#L160-L196","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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>).","Prune unused networks to free subnets: docker network prune; or extend default-address-pools in daemon.json.","Verify DOCKER_NETWORK name spelling and that the target daemon (DOCKER_HOST) is the one that has/should create the network.","Create the network manually beforehand: docker network create <name>.","Check daemon logs (journalctl -u docker) for the underlying creation failure."],"exampleFix":"// before\nDOCKER_NETWORK=pentagi-net  # exists with different driver, create fails\n// after\ndocker network rm pentagi-net  # or: docker network create --driver bridge pentagi-net","handlingStrategy":"validation","validationCode":"name := cfg.DockerNetwork\nif name != \"\" {\n    nets, err := cli.NetworkList(ctx, client.NetworkListOptions{})\n    if err != nil { return err }\n    for _, n := range nets {\n        if n.Name == name { /* exists and reusable — OK */ }\n    }\n    // optionally pre-create: cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{})\n}","typeGuard":null,"tryCatchPattern":"if _, err := NewDockerClient(ctx, db, cfg); err != nil {\n    if strings.Contains(err.Error(), \"failed to ensure docker network\") {\n        log.Fatalf(\"network %q unusable: %v — inspect/prune docker networks and retry\", cfg.DockerNetwork, err)\n    }\n    return err\n}","preventionTips":["Create the network in deploy tooling (docker network create / compose networks:) before the app starts.","Run docker network prune periodically to avoid subnet exhaustion.","Keep DOCKER_NETWORK names consistent with what compose creates.","Verify the network exists on the same daemon DOCKER_HOST points to."],"tags":["docker","network","startup"],"backgroundTag":"docker-network-create-failed","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}