docker/cli · error

plugin SchemaVersion version cannot be empty

Error message

plugin SchemaVersion version cannot be empty

What it means

Every docker CLI plugin must report metadata (via its 'docker-cli-plugin-metadata' subcommand) that includes a SchemaVersion. validateSchemaVersion accepts "0.1.0" fast-path and any version with major < 2, but an empty string is rejected with this error. The plugin is still listed, but marked invalid via Plugin.Err and will not be runnable as a plugin command.

Source

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

		p.Err = newPluginError("plugin metadata does not define a vendor")
		return p, nil
	}
	return p, nil
}

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

View on GitHub (pinned to e9452d6e78)

Solutions

1. Set SchemaVersion to "0.1.0" in the plugin's metadata output
2. Build the plugin with the docker/cli-plugins helper (plugin.Run / plugin.RunPlugin) which populates schema version automatically
3. Verify the metadata by running the plugin binary directly: <plugin-binary> docker-cli-plugin-metadata and inspecting the JSON
4. Remove or replace the broken binary from the CLI plugins directory (~/.docker/cli-plugins or /usr/libexec/docker/cli-plugins)

Example fix

// before (metadata subcommand output)
{"Vendor":"example","Version":"1.0.0"}
// after
{"SchemaVersion":"0.1.0","Vendor":"example","Version":"1.0.0"}

When it happens

Trigger: A plugin binary's metadata JSON omits the SchemaVersion field or sets it to "" — i.e. the plugin author didn't populate metadata.Metadata{SchemaVersion: "0.1.0"} in the response to the metadata subcommand, or the plugin was built with a framework version that didn't set it.

Common situations: Writing a new CLI plugin by hand (not using cli-plugins/plugin.Run, which fills this in); a script or non-Go binary masquerading as a plugin returning partial JSON; corrupted or truncated plugin binaries in ~/.docker/cli-plugins; docker info / docker plugin listing showing the plugin as invalid.

Related errors

• plugin candidate path cannot be empty
• failed to parse hook template
• unexpected hook response type:
• plugin server is closed
• config file is required

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