bind-nonrecursive is deprecated, use…

Error message

bind-nonrecursive is deprecated, use bind-recursive=disabled instead

What it means

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.

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.

Example fix

// before: deprecated option
// docker run --mount type=bind,src=/data,dst=/data,bind-nonrecursive nginx

// after: current syntax
// docker run --mount type=bind,src=/data,dst=/data,bind-recursive=disabled nginx

Defensive patterns

Strategy: fallback

Validate before calling

// Detect and migrate deprecated bind-nonrecursive before calling Set
func migrateMountSpec(spec string) string {
    if strings.Contains(spec, "bind-nonrecursive") {
        spec = strings.Replace(spec, "bind-nonrecursive", "bind-recursive=disabled", 1)
    }
    return spec
}

Try / catch

if err := mountOpt.Set(value); err != nil {
    if strings.Contains(err.Error(), "bind-nonrecursive is deprecated") {
        // Auto-migrate and retry
        value = strings.Replace(value, "bind-nonrecursive", "bind-recursive=disabled", 1)
        return mountOpt.Set(value)
    }
    return err
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/03b9faaf4a33e67a. Report an issue: GitHub.

Appendix: source

Thrown at opts/mount.go:89

			mount.Source = val
			if !filepath.IsAbs(val) && strings.HasPrefix(val, ".") {
				if abs, err := filepath.Abs(val); err == nil {
					mount.Source = abs
				}
			}
		case "target", "dst", "destination":
			mount.Target = val
		case "readonly", "ro":
			mount.ReadOnly, err = parseBoolValue(key, val, hasValue)
			if err != nil {
				return err
			}
		case "consistency":
			mount.Consistency = mounttypes.Consistency(strings.ToLower(val))
		case "bind-propagation":
			ensureBindOptions(&mount).Propagation = mounttypes.Propagation(strings.ToLower(val))
		case "bind-nonrecursive":
			return errors.New("bind-nonrecursive is deprecated, use bind-recursive=disabled instead")
		case "bind-recursive":
			switch val {
			case "enabled": // read-only mounts are recursively read-only if Engine >= v25 && kernel >= v5.12, otherwise writable
				// NOP
			case "disabled": // previously "bind-nonrecursive=true"
				ensureBindOptions(&mount).NonRecursive = true
			case "writable": // conforms to the default read-only bind-mount of Docker v24; read-only mounts are recursively mounted but not recursively read-only
				ensureBindOptions(&mount).ReadOnlyNonRecursive = true
			case "readonly": // force recursively read-only, or raise an error
				ensureBindOptions(&mount).ReadOnlyForceRecursive = true
				// TODO: implicitly set propagation and error if the user specifies a propagation in a future refactor/UX polish pass
				// https://github.com/docker/cli/pull/4316#discussion_r1341974730
			default:
				return fmt.Errorf(`invalid value for %s: %s (must be "enabled", "disabled", "writable", or "readonly")`, key, val)
			}
		case "bind-create-src":
			ensureBindOptions(&mount).CreateMountpoint, err = parseBoolValue(key, val, hasValue)
			if err != nil {

View on GitHub (pinned to 4f84911bfe)