vitessio/vitess · error

failed to initialize clone support: %v

Error message

failed to initialize clone support: %v

What it means

When the mysql clone support feature flag is enabled, Vitess runs an additional init SQL script (config.InitClone) right after the default init DB script during first-time mysqld initialization. If that clone-specific script fails, this error wraps the executeMysqlScript failure and aborts startup. It exists specifically to provision the clone plugin/support needed for clone-based backups.

Source

Thrown at go/vt/mysqlctl/mysqld.go:1347

	// Wait for mysqld to be ready, using root credentials, as no
	// user is created yet.
	params := &mysql.ConnParams{
		Uname:      "root",
		UnixSocket: cnf.SocketFile,
	}
	if err = mysqld.wait(ctx, cnf, params); err != nil {
		log.Error(fmt.Sprintf("failed starting mysqld in time: %v\n%v", err, readTailOfMysqldErrorLog(cnf.ErrorLogPath)))
		return err
	}
	if initDBSQLFile == "" { // default to built-in
		if err := mysqld.executeMysqlScript(ctx, params, config.DefaultInitDB); err != nil {
			return fmt.Errorf("failed to initialize mysqld: %v", err)
		}
		// Execute clone-specific init SQL if enabled
		if mysqlCloneEnabled {
			if err := mysqld.executeMysqlScript(ctx, params, config.InitClone); err != nil {
				return fmt.Errorf("failed to initialize clone support: %v", err)
			}
		}
		return nil
	}

	// else, user specified an init db file
	sqlFile, err := os.Open(initDBSQLFile)
	if err != nil {
		return fmt.Errorf("can't open init-db-sql-file (%v): %v", initDBSQLFile, err)
	}
	defer sqlFile.Close()
	script, err := io.ReadAll(sqlFile)
	if err != nil {
		return fmt.Errorf("can't read init-db-sql-file (%v): %v", initDBSQLFile, err)
	}
	if err := mysqld.executeMysqlScript(ctx, params, string(script)); err != nil {
		return fmt.Errorf("can't run init-db-sql-file (%v): %v", initDBSQLFile, err)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the inner error for the server's message — often 'clone plugin not supported' or a SQL syntax error.
2. Verify the MySQL version/flavor supports the clone plugin (MySQL 8.0+ only) before enabling the clone flag.
3. Disable the clone feature flag if your backend does not support clone-based operations.
4. Install/enable the clone plugin manually and grant the required privileges, then re-run init.

Example fix

// before: clone flag on MariaDB
-enable_mysqld_clone=true   # MariaDB has no clone plugin
// after
-enable_mysqld_clone=false  # or use MySQL 8.0+

if mysqlCloneEnabled {
    v, err := mysqlctl.ParseVersionString(mysqlVersion)
    if err != nil || v.Major < 8 {
        return fmt.Errorf("clone support requires MySQL >= 8.0, got %s", mysqlVersion)
    }
}

func cloneSupported(flavor string, major int) bool {
    return strings.HasPrefix(flavor, "mysql") && major >= 8
}

if err := mysqld.Start(ctx, cnf, mysqldArgs, params); err != nil && strings.Contains(err.Error(), "failed to initialize clone support") {
    // disable clone flag or upgrade MySQL, wipe datadir, retry
}

When it happens

Trigger: Mysqld.Start/Init with mysqlCloneEnabled=true executes config.InitClone via executeMysqlScript after DefaultInitDB; the mysql client invocation fails (script SQL rejected by the server, plugin unavailable, permissions).

Common situations: MySQL flavor without clone plugin support (e.g. MariaDB or old MySQL < 8.0) receiving clone setup SQL; clone plugin installation denied because of missing privileges or plugin dir issues; enabling the clone flag on an unsupported version.

Related errors

• failed to initialize mysqld: %v
• can't read init-db-sql-file (%v): %v
• clone execution failed: %v
• failed to get position after clone: %v
• can't stat mysqld socket file: %v

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