{"record":{"id":"d2c43e60de701421","repo":"docker/cli","slug":"plugin-schemaversion-q-has-wrong-format-must-be","errorCode":null,"errorMessage":"plugin SchemaVersion %q has wrong format: must be <major>.<minor>.<patch>","messagePattern":"plugin SchemaVersion %q has wrong format: must be <major>\\.<minor>\\.<patch>","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cli-plugins/manager/plugin.go","lineNumber":148,"sourceCode":"\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\")\n\t}\n\n\tpCmd := exec.CommandContext(ctx, p.Path, p.Name, metadata.HookSubcommandName, string(hDataBytes)) // #nosec G204 -- ignore \"Subprocess launched with a potential tainted input or cmd arguments\"\n\tpCmd.Env = os.Environ()\n\tpCmd.Env = append(pCmd.Env, metadata.ReexecEnvvar+\"=\"+os.Args[0])","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli-plugins/manager/plugin.go#L130-L166","documentation":"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'.","triggerScenarios":"A plugin whose metadata SchemaVersion is malformed, e.g. 'v1.0.0', '1', '1.x', or contains a non-numeric major segment.","commonSituations":"Plugin authors prefixing the version with 'v' or omitting minor/patch segments, or returning a non-semver string from the plugin's metadata handshake.","solutions":["Set SchemaVersion to a plain numeric major.minor.patch string like '0.1.0' or '1.0.0'.","Drop any leading 'v' from the version.","Ensure all three components are present and numeric."],"exampleFix":"// before\nSchemaVersion: \"v1.0.0\"\n// after\nSchemaVersion: \"1.0.0\"","handlingStrategy":"validation","validationCode":"if version != \"0.1.0\" {\n    parts := strings.SplitN(version, \".\", 3)\n    if len(parts) != 3 { return errors.New(\"schema version must be major.minor.patch\") }\n    if _, err := strconv.Atoi(parts[0]); err != nil { return errors.New(\"major must be integer\") }\n}","typeGuard":null,"tryCatchPattern":"if err := validateSchemaVersion(v); err != nil {\n    p.Err = &pluginError{cause: err}\n}","preventionTips":["Use plain numeric semver for SchemaVersion with no leading 'v'.","Provide all three major.minor.patch components."],"tags":["cli-plugins","plugins","schema-version","metadata"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}