{"record":{"id":"5bfee1ac3ca43cd5","repo":"docker/cli","slug":"network-s-network-external-name-and-network-name","errorCode":null,"errorMessage":"network %s: network.external.name and network.name conflict; only use network.name","messagePattern":"network (.+?): network\\.external\\.name and network\\.name conflict; only use network\\.name","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/loader/loader.go","lineNumber":554,"sourceCode":"\t}\n}\n\n// LoadNetworks produces a NetworkConfig map from a compose file Dict\n// the source Dict is not validated if directly used. Use Load() to enable validation\nfunc LoadNetworks(source map[string]any, version string) (map[string]types.NetworkConfig, error) {\n\tnetworks := make(map[string]types.NetworkConfig)\n\terr := Transform(source, &networks)\n\tif err != nil {\n\t\treturn networks, err\n\t}\n\tfor name, nw := range networks {\n\t\tif !nw.External.External {\n\t\t\tcontinue\n\t\t}\n\t\tswitch {\n\t\tcase nw.External.Name != \"\":\n\t\t\tif nw.Name != \"\" {\n\t\t\t\treturn nil, fmt.Errorf(\"network %s: network.external.name and network.name conflict; only use network.name\", name)\n\t\t\t}\n\t\t\tif versions.GreaterThanOrEqualTo(version, \"3.5\") {\n\t\t\t\tlogrus.Warnf(\"network %s: network.external.name is deprecated in favor of network.name\", name)\n\t\t\t}\n\t\t\tnw.Name = nw.External.Name\n\t\t\tnw.External.Name = \"\"\n\t\tcase nw.Name == \"\":\n\t\t\tnw.Name = name\n\t\t}\n\t\tnw.Extras = loadExtras(name, source)\n\t\tnetworks[name] = nw\n\t}\n\treturn networks, nil\n}\n\nfunc externalVolumeError(volume, key string) error {\n\treturn fmt.Errorf(`conflicting parameters \"external\" and %q specified for volume %q`, key, volume)\n}","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/loader/loader.go#L536-L572","documentation":"Thrown by LoadNetworks when a network has `external: true` (or `external: { name: ... }`) and BOTH `external.name` (deprecated) and the top-level `name` are set. Compose treats these as mutually exclusive because they both try to rename the external resource.","triggerScenarios":"A compose file declares a network with `external: { name: foo }` AND `name: bar` under the same network entry. Reached only when `nw.External.External` is true and `External.Name` is non-empty.","commonSituations":"Migrating from the deprecated `external.name` syntax to `name` and leaving both in place; merging two compose files that each set a different field.","solutions":["Delete the `external.name` key and keep only `name`.","If you rely on the deprecated form, remove the `name` key entirely."],"exampleFix":"# before\nnetworks:\n  dbnet:\n    external:\n      name: prod-dbnet\n    name: prod-dbnet\n# after\nnetworks:\n  dbnet:\n    external: true\n    name: prod-dbnet","handlingStrategy":"validation","validationCode":"// ensure a network sets at most one of external.name / name\nfunc validateNetworkName(name string, nw map[string]any) error {\n    ext, _ := nw[\"external\"]\n    var extName string\n    switch e := ext.(type) {\n    case map[string]any:\n        extName, _ = e[\"name\"].(string)\n    }\n    topName, _ := nw[\"name\"].(string)\n    isExternal := ext == true\n    if isExternal && extName != \"\" && topName != \"\" {\n        return fmt.Errorf(\"network %s: set only one of external.name or name\", name)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Standardize on `name` and treat `external.name` as deprecated.","Diff merged compose files (`docker compose config`) before applying.","Keep network rename fields in exactly one place."],"tags":["compose","network","external","conflict","deprecation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}