{"record":{"id":"0aea3676dcd50318","repo":"docker/cli","slug":"conflicting-parameters-external-and-q-specified","errorCode":null,"errorMessage":"conflicting parameters \"external\" and %q specified for volume %q","messagePattern":"conflicting parameters \"external\" and %q specified for volume %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/loader/loader.go","lineNumber":571,"sourceCode":"\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}\n\n// LoadVolumes produces a VolumeConfig map from a compose file Dict\n// the source Dict is not validated if directly used. Use Load() to enable validation\nfunc LoadVolumes(source map[string]any, version string) (map[string]types.VolumeConfig, error) {\n\tvolumes := make(map[string]types.VolumeConfig)\n\tif err := Transform(source, &volumes); err != nil {\n\t\treturn volumes, err\n\t}\n\n\tfor name, volume := range volumes {\n\t\tif !volume.External.External {\n\t\t\tcontinue\n\t\t}\n\t\tswitch {\n\t\tcase volume.Driver != \"\":\n\t\t\treturn nil, externalVolumeError(name, \"driver\")\n\t\tcase len(volume.DriverOpts) > 0:","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/loader/loader.go#L553-L589","documentation":"Returned by externalVolumeError from LoadVolumes. A volume marked `external: true` references an existing Docker volume, so it cannot also define `driver`, `driver_opts`, or `labels` (those only apply to volumes Docker would create). The function checks each key in order and reports the first conflicting one.","triggerScenarios":"A volume entry has `external: true` together with `driver:`, `driver_opts:`, or `labels:`.","commonSituations":"Converting a managed volume to external and forgetting to strip the driver/labels; mixing two snippets where one was local and one external.","solutions":["If the volume is truly external, remove `driver`, `driver_opts`, and `labels`.","If you need a driver/labels, set `external: false` (or omit it) so Docker creates the volume."],"exampleFix":"# before\nvolumes:\n  data:\n    external: true\n    driver: nfs\n    driver_opts:\n      share: nfs:/exports\n# after\nvolumes:\n  data:\n    external: true\n    name: prod-data","handlingStrategy":"validation","validationCode":"func validateExternalVolume(name string, vol map[string]any) error {\n    ext, _ := vol[\"external\"]\n    if ext != true && (ext == nil || reflect.ValueOf(ext).Kind() != reflect.Map) {\n        return nil\n    }\n    for _, k := range []string{\"driver\", \"driver_opts\", \"labels\"} {\n        if _, ok := vol[k]; ok {\n            return fmt.Errorf(\"volume %s: external conflicts with %s\", name, k)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat `external: true` as read-only: no driver/labels.","When converting a managed volume to external, delete creation-time keys.","Validate with `docker compose config`."],"tags":["compose","volume","external","conflict","driver"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}