docker/cli · error

invalid storage option

Error message

invalid storage option

What it means

Raised in parseStorageOpts (opts.go:982-992) when a --storage-opt value does not contain an '=' separator. Storage options are forwarded to the daemon's storage driver as key=value pairs (e.g. size=10G for overlay2 on xfs), so a bare token cannot be turned into a map entry.

Source

Thrown at cli/command/container/opts.go:987

	for _, opt := range securityOpts {
		if opt == "systempaths=unconfined" {
			maskedPaths = []string{}
			readonlyPaths = []string{}
		} else {
			filtered = append(filtered, opt)
		}
	}

	return filtered, maskedPaths, readonlyPaths
}

// parses storage options per container into a map
func parseStorageOpts(storageOpts []string) (map[string]string, error) {
	m := make(map[string]string)
	for _, option := range storageOpts {
		k, v, ok := strings.Cut(option, "=")
		if !ok {
			return nil, errors.New("invalid storage option")
		}
		m[k] = v
	}
	return m, nil
}

// parseDevice parses a device mapping string to a container.DeviceMapping struct
func parseDevice(device, serverOS string) (container.DeviceMapping, error) {
	switch serverOS {
	case "linux":
		return parseLinuxDevice(device)
	case "windows":
		// Windows doesn't support mapping, so passing the given value as-is.
		return container.DeviceMapping{PathOnHost: device}, nil
	default:
		return container.DeviceMapping{}, fmt.Errorf("unknown server OS: %s", serverOS)
	}
}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use key=value form: docker run --storage-opt size=20G ...
2. Quote the option if it contains shell-special characters: --storage-opt "size=20G"
3. Note that size= additionally requires a compatible storage driver setup (e.g. overlay2 on xfs with pquota, or windowsfilter) — the daemon validates that separately

Example fix

// before
docker run --storage-opt 20G ubuntu
// after
docker run --storage-opt size=20G ubuntu

When it happens

Trigger: `docker run --storage-opt size ...` or `--storage-opt 10G` — strings.Cut(option, "=") finds no '=', so any value without an equals sign fails; only the client-side format is checked here (key validity is checked later by the daemon).

Common situations: Forgetting the key, writing size:10G or 'size 10G' instead of size=10G; shell quoting that splits the option so only part of it reaches the flag; scripts building the option string from empty variables.

Related errors

• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• config file is required
• source can not be empty
• no name set for network

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/7bee637052e9e7e8.json. Report an issue: GitHub.