docker/cli · warning

plugin SchemaVersion

Error message

plugin SchemaVersion %q is not supported: must be lower than 2.0.0

What it means

Returned by validateSchemaVersion when the parsed major version is >= 2, i.e. the plugin uses a schema newer than this CLI supports. The CLI accepts major 0 and 1 only; 2.0.0 and above are rejected as unsupported, preserving forward compatibility.

Solutions

1. Upgrade the Docker CLI to a version that supports the plugin's schema.
2. Pin/use a plugin version that targets schema 0.1.0 or 1.x with the current CLI.
3. If authoring the plugin, target schema 0.1.0 or 1.x for broad compatibility.

Example fix

// before
SchemaVersion: "2.0.0"
// after
SchemaVersion: "1.0.0"

major, _, _ := strings.Cut(version, ".")
m, _ := strconv.Atoi(major)
if m >= 2 {
    return fmt.Errorf("schema %s unsupported; upgrade CLI or pin plugin to schema < 2.0.0", version)
}

if err := validateSchemaVersion(v); err != nil {
    // mark plugin invalid but do not crash
}

When it happens

Trigger: A plugin built against a future schema version (2.x.y) run by an older CLI that only knows schemas < 2.0.0.

Common situations: Mixing a newer plugin with an older Docker CLI, where the plugin adopted a not-yet-supported schema.

Related errors

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

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

Appendix: source

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

// 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])

	out, err := pCmd.Output()
	if err != nil {

View on GitHub (pinned to 4f84911bfe)