vitessio/vitess · error · ErrMySQLShellPreCheck

%w: no backup location set via --mysql-shell-backup-location

Error message

%w: no backup location set via --mysql-shell-backup-location

What it means

The MySQL Shell backup engine requires the --mysql-shell-backup-location flag to know where dumps are written. backupPreCheck() returns this error, wrapping ErrMySQLShellPreCheck, when that flag is empty. It fails fast at the start of ExecuteBackup before any expensive dump work begins.

Source

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

	return false
}

// backupLocation returns a backup location path by joining the configured
// mysqlShellBackupLocation with the provided directory and name components.
// For local filesystem mode, it uses fileutil.SafePathJoin to prevent path
// traversal outside the configured backup location. For object storage,
// path.Join is used since SafePathJoin relies on OS-native path operations
// that don't understand cloud URIs.
func (be *MySQLShellBackupEngine) backupLocation(dir, name string) (string, error) {
	if isObjectStoreFlags(mysqlShellDumpFlags) {
		return path.Join(mysqlShellBackupLocation, dir, name), nil
	}
	return fileutil.SafePathJoin(mysqlShellBackupLocation, dir, name)
}

func (be *MySQLShellBackupEngine) backupPreCheck(location string) error {
	if mysqlShellBackupLocation == "" {
		return fmt.Errorf("%w: no backup location set via --mysql-shell-backup-location", ErrMySQLShellPreCheck)
	}

	if mysqlShellFlags == "" || !strings.Contains(mysqlShellFlags, "--js") {
		return fmt.Errorf("%w: at least the --js flag is required in the value of the flag --mysql-shell-flags", ErrMySQLShellPreCheck)
	}

	// make sure the target directory exists if the target location for the backup is not an object store
	// (e.g. is the local filesystem) as MySQL Shell doesn't create the entire path beforehand:
	if !isObjectStoreFlags(mysqlShellDumpFlags) {
		err := os.MkdirAll(location, 0o750)
		if err != nil {
			return fmt.Errorf("failure creating directory %s: %w", location, err)
		}
	}

	return nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Add --mysql-shell-backup-location /path/to/backups to the vttablet/vtbackup startup flags.
2. Verify the flag value is non-empty in the process environment or config management output (`ps` or flags file).
3. If the engine should not be mysqlshell, fix the --backup-engine-standalone flag instead.

Example fix

// before: vttablet started without the flag
--backup-engine-standalone mysqlshell
// after: supply the required location
--backup-engine-standalone mysqlshell \
  --mysql-shell-backup-location /vt/backups

if backupEngine == "mysqlshell" && mysqlShellBackupLocation == "" {
	return errors.New("--mysql-shell-backup-location is required for the mysqlshell backup engine")
}

err := engine.ExecuteBackup(ctx, backupParams)
if err != nil {
	var preErr error
	if errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) {
		// config problem, not transient: fail deployment, don't retry
		preErr = err
	}
	return preErr
}

When it happens

Trigger: Calling MySQLShellBackupEngine.ExecuteBackup when the `mysql-shell-backup-location` flag (mysqlShellBackupLocation) was never set or is set to empty string.

Common situations: Switching a tablet's backup engine to mysqlshell without adding the required flags to the vttablet/vtbackup command line; config templates that omit mysqlshell-specific settings; flags set only on some shards' deployments.

Related errors

• --s3-backup-storage-bucket required
• %w: at least the --js flag is required in the value of the f
• cannot perform backup without my.cnf, please restart vttable
• %w value: %q
• error parsing the json file : %v

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