vitessio/vitess · error

ErrMySQLShellPreCheck

ErrMySQLShellPreCheck

Error message

ErrMySQLShellPreCheck

What it means

ErrMySQLShellPreCheck is the sentinel error returned when a MySQL Shell-based backup or restore pre-check fails (backupPreCheck/restorePreCheck). Callers are expected to compare with errors.Is to detect this specific condition and take the mysql-shell-specific code path, e.g. skipping the version compatibility check on restore or reporting missing object-store parameters. It is deliberately a sentinel so callers can distinguish pre-check failures from actual backup execution errors.

Solutions

1. Use errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) to branch on this error rather than string matching
2. Fix the pre-check inputs: supply all required object-store parameters for the chosen cloud storage
3. Verify the MySQL version is compatible with the installed MySQL Shell dump/load utilities before running
4. Consult the pre-check log messages for the exact parameter that failed

Example fix

// before
if err != nil && strings.Contains(err.Error(), "ErrMySQLShellPreCheck") { ... }
// after
if errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) { /* handle pre-check failure */ }

// validate params before invoking the pre-check
for _, k := range []string{"s3BucketName", "osBucketName", "azureContainerName"} {
    if _, ok := params[k]; !ok {
        return fmt.Errorf("missing object store param %q for mysqlshell backup", k)
    }
}

func isMySQLShellPreCheckErr(err error) bool {
    return errors.Is(err, mysqlctl.ErrMySQLShellPreCheck)
}

err := engine.Backup(ctx, ...)
if err != nil {
    if errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) {
        // fix config/version issues and retry pre-check
        return handlePreCheckFailure(err)
    }
    return err
}

When it happens

Trigger: Calling backupPreCheck or restorePreCheck with mysqlshell engine parameters that fail validation — e.g. missing required object-store parameters (s3BucketName, osBucketName, azureContainerName) or incompatible MySQL version — and TestMySQLShellBackupBackupPreCheck detecting the same conditions.

Common situations: Configuring mysqlshell backups with an incomplete storage configuration (no S3 bucket / OS bucket / Azure container); running against a MySQL version unsupported by the configured MySQL Shell dump/load utilities.

Related errors

• AbortBackup cannot be called on read-only backup
• AddFile cannot be called on read-only backup
• could not auto-detect MySQL version
• deadline exceeded waiting for mysqld socket file to appear:
• EndBackup cannot be called on read-only backup

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

Appendix: source

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

	// location to store the mysql shell backup
	mysqlShellBackupLocation = ""
	// flags passed to the mysql shell utility, used both on dump/restore
	mysqlShellFlags = "--defaults-file=/dev/null --js -h localhost"
	// flags passed to the Dump command, as a JSON string
	mysqlShellDumpFlags = `{"threads": 4}`
	// flags passed to the Load command, as a JSON string
	mysqlShellLoadFlags = `{"threads": 4, "loadUsers": true, "updateGtidSet": "replace", "skipBinlog": true, "progressFile": ""}`
	// drain a tablet when taking a backup
	mysqlShellBackupShouldDrain = false
	// disable redo logging and double write buffer
	mysqlShellSpeedUpRestore = false
	// skip the MySQL version compatibility check when restoring from a mysql-shell backup
	mysqlShellRestoreSkipVersionCheck = false

	// use when checking if we need to create the directory on the local filesystem or not.
	knownObjectStoreParams = []string{"s3BucketName", "osBucketName", "azureContainerName"}

	ErrMySQLShellPreCheck = errors.New("ErrMySQLShellPreCheck")

	// internal databases not backed up by MySQL Shell
	internalDBs = []string{
		"information_schema", "mysql", "ndbinfo", "performance_schema", "sys",
	}
	// reserved MySQL users https://dev.mysql.com/doc/refman/8.0/en/reserved-accounts.html
	reservedUsers = []string{
		"mysql.sys@localhost", "mysql.session@localhost", "mysql.infoschema@localhost",
	}
)

// MySQLShellBackupManifest represents a backup.
type MySQLShellBackupManifest struct {
	// BackupManifest is an anonymous embedding of the base manifest struct.
	// Note that the manifest itself doesn't fill the Position field, as we have
	// no way of fetching that information from mysqlsh at the moment.
	BackupManifest

View on GitHub (pinned to 01a25a7d17)