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.

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)

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

• ReadFile cannot be called on read-write backup
• AddFile cannot be called on read-only backup
• EndBackup cannot be called on read-only backup
• AbortBackup cannot be called on read-only backup
• ReadFile cannot be called on read-write backup

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