docker/cli · warning

plugin SchemaVersion

Error message

plugin SchemaVersion %q has wrong format: must be <major>.<minor>.<patch>

What it means

Returned by validateSchemaVersion when the plugin's SchemaVersion is not the special '0.1.0' and cannot be split into a numeric major version via strings.Cut on '.' followed by strconv.Atoi. The version must follow semantic <major>.<minor>.<patch> form, e.g. '1.2.0'.

Solutions

1. Set SchemaVersion to a plain numeric major.minor.patch string like '0.1.0' or '1.0.0'.
2. Drop any leading 'v' from the version.
3. Ensure all three components are present and numeric.

Example fix

// before
SchemaVersion: "v1.0.0"
// after
SchemaVersion: "1.0.0"

if version != "0.1.0" {
    parts := strings.SplitN(version, ".", 3)
    if len(parts) != 3 { return errors.New("schema version must be major.minor.patch") }
    if _, err := strconv.Atoi(parts[0]); err != nil { return errors.New("major must be integer") }
}

if err := validateSchemaVersion(v); err != nil {
    p.Err = &pluginError{cause: err}
}

When it happens

Trigger: A plugin whose metadata SchemaVersion is malformed, e.g. 'v1.0.0', '1', '1.x', or contains a non-numeric major segment.

Common situations: Plugin authors prefixing the version with 'v' or omitting minor/patch segments, or returning a non-semver string from the plugin's metadata handshake.

Related errors

• plugin SchemaVersion
• plugin SchemaVersion version cannot be empty
• docker: unknown command: docker
• failed to unmarshal hook response
• unable to determine basename of plugin candidate

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

Appendix: source

Thrown at cli-plugins/manager/plugin.go:148

// validateSchemaVersion validates if the plugin's schemaVersion is supported.
//
// The current schema-version is "0.1.0", but we don't want to break compatibility
// until v2.0.0 of the schema version. Check for the major version to be < 2.0.0.
//
// Note that CLI versions before 28.4.1 may not support these versions as they were
// hard-coded to only accept "0.1.0".
func validateSchemaVersion(version string) error {
	if version == "0.1.0" {
		return nil
	}
	if version == "" {
		return errors.New("plugin SchemaVersion version cannot be empty")
	}
	major, _, ok := strings.Cut(version, ".")
	majorVersion, err := strconv.Atoi(major)
	if !ok || err != nil {
		return fmt.Errorf("plugin SchemaVersion %q has wrong format: must be <major>.<minor>.<patch>", version)
	}
	if majorVersion > 1 {
		return fmt.Errorf("plugin SchemaVersion %q is not supported: must be lower than 2.0.0", version)
	}
	return nil
}

// RunHook executes the plugin's hooks command
// and returns its unprocessed output.
func (p *Plugin) RunHook(ctx context.Context, hookData hooks.Request) ([]byte, error) {
	hDataBytes, err := json.Marshal(hookData)
	if err != nil {
		return nil, wrapAsPluginError(err, "failed to marshall hook data")
	}

	pCmd := exec.CommandContext(ctx, p.Path, p.Name, metadata.HookSubcommandName, string(hDataBytes)) // #nosec G204 -- ignore "Subprocess launched with a potential tainted input or cmd arguments"
	pCmd.Env = os.Environ()
	pCmd.Env = append(pCmd.Env, metadata.ReexecEnvvar+"="+os.Args[0])

View on GitHub (pinned to 4f84911bfe)