vitessio/vitess · error · ErrMySQLShellPreCheck

%w: failed to fetch MySQL version: %v

Error message

%w: failed to fetch MySQL version: %v

What it means

When the mysqlShellSpeedUpRestore option is enabled, restorePreCheck fetches the target MySQL server version via Mysqld.GetVersionString to verify it supports disabling the redo log. This error wraps the failure to obtain that version string from the mysqld instance.

Source

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

		return false, fmt.Errorf("%w: mysql-shell needs to restore with updateGtidSet set to \"replace\" to work with Vitess", ErrMySQLShellPreCheck)
	}

	if val, ok := loadFlags["progressFile"]; !ok || val != "" {
		return false, fmt.Errorf("%w: \"progressFile\" needs to be empty as vitess always starts a restore from scratch", ErrMySQLShellPreCheck)
	}

	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)
		}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Confirm mysqld is running and reachable from the tablet (check socket/port settings)
2. Test manually: run `SELECT @@version` as the Vitess DBA user on the target instance
3. Fix or remove the mysqlShellSpeedUpRestore setting if the speed-up path is not required

// ensure mysqld is reachable first
version, err := mysqld.GetVersionString(ctx)
if err != nil {
    log.Warn("mysqld unreachable before restore", slog.Any("error", err))
}

if _, err := engine.ExecuteRestore(ctx, params, backupDir); err != nil {
    if strings.Contains(err.Error(), "failed to fetch MySQL version") {
        // verify mysqld is up, then retry restore
    }
}

When it happens

Trigger: ExecuteRestore -> restorePreCheck with mysqlShellSpeedUpRestore=true when GetVersionString fails on the underlying DBA connection, e.g. mysqld not running, socket/port misconfigured, or the query for @@version fails.

Common situations: Restore attempted before mysqld is fully started; wrong mysqld socket/port in the tablet's params; permissions issue preventing the super-query used to read the version.

Related errors

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

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