vitessio/vitess · error · ErrMySQLShellPreCheck

%w: failed to parse MySQL version (version: %s): %v

Error message

%w: failed to parse MySQL version (version: %s): %v

What it means

After fetching the raw version string, restorePreCheck calls ParseVersionString to extract major/minor/patch components. This error is thrown when the version string returned by the server cannot be parsed by Vitess' version parser, so capability checking cannot proceed.

Source

Thrown at go/vt/mysqlctl/mysqlshellbackupengine.go:534

	}

	if val, ok := loadFlags["skipBinlog"]; !ok || val != true {
		return false, fmt.Errorf("%w: \"skipBinlog\" needs to set to true", ErrMySQLShellPreCheck)
	}

	if val, ok := loadFlags["loadUsers"]; ok && val == true {
		shouldDeleteUsers = true
	}

	if mysqlShellSpeedUpRestore {
		version, err := params.Mysqld.GetVersionString(ctx)
		if err != nil {
			return false, fmt.Errorf("%w: failed to fetch MySQL version: %v", ErrMySQLShellPreCheck, err)
		}

		_, sv, err := ParseVersionString(version)
		if err != nil {
			return false, fmt.Errorf("%w: failed to parse MySQL version (version: %s): %v", ErrMySQLShellPreCheck, version, err)
		}

		versionStr := fmt.Sprintf("%d.%d.%d", sv.Major, sv.Minor, sv.Patch)

		capableOf := mysql.ServerVersionCapableOf(versionStr)
		capable, err := capableOf(capabilities.DisableRedoLogFlavorCapability)
		if err != nil {
			return false, fmt.Errorf("%w: error checking if server supports disabling redo log: %v", ErrMySQLShellPreCheck, err)
		}

		if !capable {
			return false, fmt.Errorf("%w: MySQL version doesn't support disabling the redo log (must be >=8.0.21, current version: %s)", ErrMySQLShellPreCheck, versionStr)
		}
	}

	return shouldDeleteUsers, nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the actual `SELECT @@version` output and confirm it is a parseable MySQL-style version (e.g. 8.0.34)
2. Use a supported MySQL 8.0.21+ server for the mysql-shell speed-up restore
3. Disable mysqlShellSpeedUpRestore if the server flavor/version cannot be recognized

version, err := mysqld.GetVersionString(ctx)
if err == nil {
    if _, _, perr := mysqlctl.ParseVersionString(version); perr != nil {
        log.Warn("unparseable MySQL version for mysql-shell speed-up", slog.String("version", version))
    }
}

if _, err := engine.ExecuteRestore(ctx, params, backupDir); err != nil {
    if strings.Contains(err.Error(), "failed to parse MySQL version") {
        // disable mysqlShellSpeedUpRestore or switch to a standard MySQL server
    }
}

When it happens

Trigger: ExecuteRestore -> restorePreCheck with mysqlShellSpeedUpRestore=true when ParseVersionString(version) returns an error for the server's version string (e.g. MariaDB or vendor-modified version strings that don't match the expected MySQL format).

Common situations: Running MySQL Shell restore speed-up against MariaDB or Percona builds with unusual version strings; patched/custom mysqld builds reporting non-standard @@version output.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• %w: "progressFile" needs to be empty as vitess always starts
• %w: "skipBinlog" needs to set to true
• %w: failed to fetch MySQL version: %v
• %w: error checking if server supports disabling redo log: %v
• %w: MySQL version doesn't support disabling the redo log (mu

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/20f0acea817e2bf5. Report an issue: GitHub.