vitessio/vitess · error · ErrMySQLShellPreCheck

%w: at least the --js flag is required in the value of the f

Error message

%w: at least the --js flag is required in the value of the flag --mysql-shell-flags

What it means

The MySQL Shell engine drives dumps via JS mode, so the --mysql-shell-flags value must contain at least the --js flag. backupPreCheck() wraps ErrMySQLShellPreCheck with this message when mysqlShellFlags is empty or lacks "--js". Backup aborts before the dump starts.

Source

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

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

func (be *MySQLShellBackupEngine) restorePreCheck(ctx context.Context, params RestoreParams) (shouldDeleteUsers bool, err error) {
	if mysqlShellFlags == "" {
		return shouldDeleteUsers, fmt.Errorf("%w: at least the --js flag is required in the value of the flag --mysql-shell-flags", ErrMySQLShellPreCheck)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Set --mysql-shell-flags to include --js, e.g. --mysql-shell-flags "--js --defaults-file=/etc/my.cnf".
2. Verify the value contains the literal "--js" (grep the process args).
3. Keep any extra util flags (like --defaults-extra-file) alongside --js rather than replacing it.

Example fix

// before: missing --js
--mysql-shell-flags "--defaults-file=/etc/my.cnf"
// after
--mysql-shell-flags "--js --defaults-file=/etc/my.cnf"

if !strings.Contains(mysqlShellFlags, "--js") {
	return errors.New("--mysql-shell-flags must contain at least --js")
}

err := engine.ExecuteBackup(ctx, backupParams)
if errors.Is(err, mysqlctl.ErrMySQLShellPreCheck) {
	// inspect message: missing --js means flag misconfiguration; fix config and restart
	return err
}

When it happens

Trigger: Calling MySQLShellBackupEngine.ExecuteBackup when mysqlShellFlags is "" or its value does not contain the substring --js (e.g. flags set to only --defaults-file=...).

Common situations: Operators copy flag strings from MySQL Shell docs that omit --js; --mysql-shell-flags left at default empty value; typos like "-js" or "--javascript".

Related errors

• %w: no backup location set via --mysql-shell-backup-location
• --s3-backup-storage-bucket required
• 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/b06a93bc28cb80ea. Report an issue: GitHub.