{"record":{"id":"03b9faaf4a33e67a","repo":"docker/cli","slug":"bind-nonrecursive-is-deprecated-use-bind-recursiv","errorCode":null,"errorMessage":"bind-nonrecursive is deprecated, use bind-recursive=disabled instead","messagePattern":"bind-nonrecursive is deprecated, use bind-recursive=disabled instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"opts/mount.go","lineNumber":89,"sourceCode":"\t\t\tmount.Source = val\n\t\t\tif !filepath.IsAbs(val) && strings.HasPrefix(val, \".\") {\n\t\t\t\tif abs, err := filepath.Abs(val); err == nil {\n\t\t\t\t\tmount.Source = abs\n\t\t\t\t}\n\t\t\t}\n\t\tcase \"target\", \"dst\", \"destination\":\n\t\t\tmount.Target = val\n\t\tcase \"readonly\", \"ro\":\n\t\t\tmount.ReadOnly, err = parseBoolValue(key, val, hasValue)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\tcase \"consistency\":\n\t\t\tmount.Consistency = mounttypes.Consistency(strings.ToLower(val))\n\t\tcase \"bind-propagation\":\n\t\t\tensureBindOptions(&mount).Propagation = mounttypes.Propagation(strings.ToLower(val))\n\t\tcase \"bind-nonrecursive\":\n\t\t\treturn errors.New(\"bind-nonrecursive is deprecated, use bind-recursive=disabled instead\")\n\t\tcase \"bind-recursive\":\n\t\t\tswitch val {\n\t\t\tcase \"enabled\": // read-only mounts are recursively read-only if Engine >= v25 && kernel >= v5.12, otherwise writable\n\t\t\t\t// NOP\n\t\t\tcase \"disabled\": // previously \"bind-nonrecursive=true\"\n\t\t\t\tensureBindOptions(&mount).NonRecursive = true\n\t\t\tcase \"writable\": // conforms to the default read-only bind-mount of Docker v24; read-only mounts are recursively mounted but not recursively read-only\n\t\t\t\tensureBindOptions(&mount).ReadOnlyNonRecursive = true\n\t\t\tcase \"readonly\": // force recursively read-only, or raise an error\n\t\t\t\tensureBindOptions(&mount).ReadOnlyForceRecursive = true\n\t\t\t\t// TODO: implicitly set propagation and error if the user specifies a propagation in a future refactor/UX polish pass\n\t\t\t\t// https://github.com/docker/cli/pull/4316#discussion_r1341974730\n\t\t\tdefault:\n\t\t\t\treturn fmt.Errorf(`invalid value for %s: %s (must be \"enabled\", \"disabled\", \"writable\", or \"readonly\")`, key, val)\n\t\t\t}\n\t\tcase \"bind-create-src\":\n\t\t\tensureBindOptions(&mount).CreateMountpoint, err = parseBoolValue(key, val, hasValue)\n\t\t\tif err != nil {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/opts/mount.go#L71-L107","documentation":"Returned by MountOpt.Set (opts/mount.go:89) when the deprecated 'bind-nonrecursive' option is encountered in a --mount string. This option was replaced by 'bind-recursive=disabled' and now unconditionally errors to force migration. The error message directs the user to the replacement syntax.","triggerScenarios":"A --mount value contains the field 'bind-nonrecursive' (with or without a value), e.g., '--mount type=bind,src=/x,dst=/y,bind-nonrecursive'. The switch case at line 88 immediately returns this deprecation error.","commonSituations":"Upgrading Docker CLI from a version that accepted 'bind-nonrecursive' to a newer version that removed it, existing scripts or CI pipelines using the old option name, or documentation/examples referencing the deprecated syntax.","solutions":["Replace 'bind-nonrecursive' with 'bind-recursive=disabled' in the --mount flag.","Update any scripts, CI configs, or documentation that reference the old option name.","Audit compose files for the deprecated option."],"exampleFix":"// before: deprecated option\n// docker run --mount type=bind,src=/data,dst=/data,bind-nonrecursive nginx\n\n// after: current syntax\n// docker run --mount type=bind,src=/data,dst=/data,bind-recursive=disabled nginx","handlingStrategy":"fallback","validationCode":"// Detect and migrate deprecated bind-nonrecursive before calling Set\nfunc migrateMountSpec(spec string) string {\n    if strings.Contains(spec, \"bind-nonrecursive\") {\n        spec = strings.Replace(spec, \"bind-nonrecursive\", \"bind-recursive=disabled\", 1)\n    }\n    return spec\n}","typeGuard":null,"tryCatchPattern":"if err := mountOpt.Set(value); err != nil {\n    if strings.Contains(err.Error(), \"bind-nonrecursive is deprecated\") {\n        // Auto-migrate and retry\n        value = strings.Replace(value, \"bind-nonrecursive\", \"bind-recursive=disabled\", 1)\n        return mountOpt.Set(value)\n    }\n    return err\n}","preventionTips":["Migrate all uses of 'bind-nonrecursive' to 'bind-recursive=disabled'.","Search scripts and CI configs for 'bind-nonrecursive' after upgrading Docker CLI.","Update documentation and examples to use the current 'bind-recursive=' syntax."],"tags":["mount","deprecated","bind","cli-flag"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}