{"id":"2399e081dd0eae0b","repo":"docker/cli","slug":"plugin-schemaversion-version-cannot-be-empty","errorCode":null,"errorMessage":"plugin SchemaVersion version cannot be empty","messagePattern":"plugin SchemaVersion version cannot be empty","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli-plugins/manager/plugin.go","lineNumber":143,"sourceCode":"\t\tp.Err = newPluginError(\"plugin metadata does not define a vendor\")\n\t\treturn p, nil\n\t}\n\treturn p, nil\n}\n\n// validateSchemaVersion validates if the plugin's schemaVersion is supported.\n//\n// The current schema-version is \"0.1.0\", but we don't want to break compatibility\n// until v2.0.0 of the schema version. Check for the major version to be < 2.0.0.\n//\n// Note that CLI versions before 28.4.1 may not support these versions as they were\n// hard-coded to only accept \"0.1.0\".\nfunc validateSchemaVersion(version string) error {\n\tif version == \"0.1.0\" {\n\t\treturn nil\n\t}\n\tif version == \"\" {\n\t\treturn errors.New(\"plugin SchemaVersion version cannot be empty\")\n\t}\n\tmajor, _, ok := strings.Cut(version, \".\")\n\tmajorVersion, err := strconv.Atoi(major)\n\tif !ok || err != nil {\n\t\treturn fmt.Errorf(\"plugin SchemaVersion %q has wrong format: must be <major>.<minor>.<patch>\", version)\n\t}\n\tif majorVersion > 1 {\n\t\treturn fmt.Errorf(\"plugin SchemaVersion %q is not supported: must be lower than 2.0.0\", version)\n\t}\n\treturn nil\n}\n\n// RunHook executes the plugin's hooks command\n// and returns its unprocessed output.\nfunc (p *Plugin) RunHook(ctx context.Context, hookData hooks.Request) ([]byte, error) {\n\thDataBytes, err := json.Marshal(hookData)\n\tif err != nil {\n\t\treturn nil, wrapAsPluginError(err, \"failed to marshall hook data\")","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli-plugins/manager/plugin.go#L125-L161","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set SchemaVersion to \"0.1.0\" in the plugin's metadata output","Build the plugin with the docker/cli-plugins helper (plugin.Run / plugin.RunPlugin) which populates schema version automatically","Verify the metadata by running the plugin binary directly: <plugin-binary> docker-cli-plugin-metadata and inspecting the JSON","Remove or replace the broken binary from the CLI plugins directory (~/.docker/cli-plugins or /usr/libexec/docker/cli-plugins)"],"exampleFix":"// before (metadata subcommand output)\n{\"Vendor\":\"example\",\"Version\":\"1.0.0\"}\n// after\n{\"SchemaVersion\":\"0.1.0\",\"Vendor\":\"example\",\"Version\":\"1.0.0\"}","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","cli-plugins","metadata","schema-version","validation"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}