{"record":{"id":"b2736efb312a6ca2","repo":"vitessio/vitess","slug":"w-skipbinlog-needs-to-set-to-true","errorCode":null,"errorMessage":"%w: \"skipBinlog\" needs to set to true","messagePattern":"%w: \"skipBinlog\" needs to set to true","errorType":"error_code","errorClass":"ErrMySQLShellPreCheck","httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/mysqlshellbackupengine.go","lineNumber":519,"sourceCode":"\t\treturn shouldDeleteUsers, fmt.Errorf(\"%w: at least the --js flag is required in the value of the flag --mysql-shell-flags\", ErrMySQLShellPreCheck)\n\t}\n\n\tloadFlags := map[string]any{}\n\terr = json.Unmarshal([]byte(mysqlShellLoadFlags), &loadFlags)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"%w: unable to parse JSON of load flags\", ErrMySQLShellPreCheck)\n\t}\n\n\tif val, ok := loadFlags[\"updateGtidSet\"]; !ok || val != \"replace\" {\n\t\treturn false, fmt.Errorf(\"%w: mysql-shell needs to restore with updateGtidSet set to \\\"replace\\\" to work with Vitess\", ErrMySQLShellPreCheck)\n\t}\n\n\tif val, ok := loadFlags[\"progressFile\"]; !ok || val != \"\" {\n\t\treturn false, fmt.Errorf(\"%w: \\\"progressFile\\\" needs to be empty as vitess always starts a restore from scratch\", ErrMySQLShellPreCheck)\n\t}\n\n\tif val, ok := loadFlags[\"skipBinlog\"]; !ok || val != true {\n\t\treturn false, fmt.Errorf(\"%w: \\\"skipBinlog\\\" needs to set to true\", ErrMySQLShellPreCheck)\n\t}\n\n\tif val, ok := loadFlags[\"loadUsers\"]; ok && val == true {\n\t\tshouldDeleteUsers = true\n\t}\n\n\tif mysqlShellSpeedUpRestore {\n\t\tversion, err := params.Mysqld.GetVersionString(ctx)\n\t\tif err != nil {\n\t\t\treturn false, fmt.Errorf(\"%w: failed to fetch MySQL version: %v\", ErrMySQLShellPreCheck, err)\n\t\t}\n\n\t\t_, sv, err := ParseVersionString(version)\n\t\tif err != nil {\n\t\t\treturn false, fmt.Errorf(\"%w: failed to parse MySQL version (version: %s): %v\", ErrMySQLShellPreCheck, version, err)\n\t\t}\n\n\t\tversionStr := fmt.Sprintf(\"%d.%d.%d\", sv.Major, sv.Minor, sv.Patch)","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/mysqlshellbackupengine.go#L501-L537","documentation":"restorePreCheck requires mysql-shell's load dump utility to run with skipBinlog=true. During a Vitess restore, replication recovery is driven by the restored GTID position and applying the load through the binary log would be wrong and slow. The check rejects any loadFlags where \"skipBinlog\" is missing or not the boolean true.","triggerScenarios":"ExecuteRestore -> restorePreCheck when loadFlags[\"skipBinlog\"] is absent, set to false, or set to a non-boolean value (e.g. string \"true\"), which fails the `!= true` comparison.","commonSituations":"Operators add skipBinlog as a YAML/JSON string \"true\" instead of boolean true; the flag is simply omitted from a hand-written loadFlags block; a config translated from a mysql-shell CLI example omits the flag because it isn't a CLI flag on their shell version.","solutions":["Set \"skipBinlog\" to boolean true in the loadFlags map of the mysql-shell backupengine config","Ensure it is a real boolean, not the string \"true\" (YAML unquoted, JSON without quotes)","Re-check the sibling required flags: updateGtidSet=replace and progressFile empty"],"exampleFix":"// before\n\"loadFlags\": {\"updateGtidSet\": \"replace\", \"skipBinlog\": \"true\"}\n// after\n\"loadFlags\": {\"updateGtidSet\": \"replace\", \"skipBinlog\": true}","handlingStrategy":"validation","validationCode":"if v, ok := loadFlags[\"skipBinlog\"]; !ok || v != true {\n    return fmt.Errorf(\"mysql-shell loadFlags.skipBinlog must be boolean true\")\n}","typeGuard":null,"tryCatchPattern":"if _, err := engine.ExecuteRestore(ctx, params, backupDir); err != nil {\n    if errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) {\n        // inspect and correct loadFlags before re-running restore\n    }\n}","preventionTips":["Write skipBinlog as an unquoted boolean in YAML/JSON configs","Include all three required flags (updateGtidSet, progressFile, skipBinlog) in a config template","Lint configs for boolean-vs-string mistakes at deploy time"],"tags":["mysql-shell","backup-restore","configuration"],"backgroundTag":"invalid-load-flags","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}