can't set semi-sync mode: %v; make sure plugins are loaded i

Error message

can't set semi-sync mode: %v; make sure plugins are loaded in my.cnf

What it means

SetSemiSyncEnabled issues `SET GLOBAL rpl_semi_sync_master_enabled` / `rpl_semi_sync_replica_enabled` variables. If MySQL rejects the statement — most commonly because the semi-sync plugin is not installed — this error wraps the server error with a hint about loading plugins in my.cnf.

Source

Thrown at go/vt/mysqlctl/replication.go:1271

func (mysqld *Mysqld) SetSemiSyncEnabled(ctx context.Context, primary, replica bool) error {
	log.Info(fmt.Sprintf("Setting semi-sync mode: primary=%v, replica=%v", primary, replica))

	// Convert bool to int.
	var p, s int
	if primary {
		p = 1
	}
	if replica {
		s = 1
	}

	query, err := mysqld.enableSemiSyncQuery(ctx)
	if err != nil {
		return err
	}
	err = mysqld.ExecuteSuperQuery(ctx, fmt.Sprintf(query, p, s))
	if err != nil {
		return fmt.Errorf("can't set semi-sync mode: %v; make sure plugins are loaded in my.cnf", err)
	}
	return nil
}

// SemiSyncEnabled returns whether semi-sync is enabled for primary or replica.
// If the semi-sync plugin is not loaded, we assume semi-sync is disabled.
func (mysqld *Mysqld) SemiSyncEnabled(ctx context.Context) (primary, replica bool) {
	vars, err := mysqld.fetchVariables(ctx, "rpl_semi_sync_%_enabled")
	if err != nil {
		return false, false
	}
	switch mysqld.SemiSyncType(ctx) {
	case mysql.SemiSyncTypeSource:
		primary = vars["rpl_semi_sync_source_enabled"] == "ON"
		replica = vars["rpl_semi_sync_replica_enabled"] == "ON"
	case mysql.SemiSyncTypeMaster:
		primary = vars["rpl_semi_sync_master_enabled"] == "ON"
		replica = vars["rpl_semi_sync_slave_enabled"] == "ON"

View on GitHub (pinned to 01a25a7d17)

Solutions

Load the semi-sync plugin: install_plugin or add `plugin-load-add=semisync_master.so;semisync_slave.so` to my.cnf and restart mysqld
Verify with `SHOW VARIABLES LIKE 'rpl_semi_sync%'` that the variables exist
For MariaDB use the MariaDB-appropriate plugin/variable names (rpl_semi_sync_source/rpl_semi_sync_replica)
Check the mysqld error log for plugin load failures (wrong .so path or version)

Example fix

// before: my.cnf without semi-sync plugin
// after: in my.cnf
// [mysqld]
// plugin-load-add=semisync_master.so
// plugin-load-add=semisync_slave.so
// rpl_semi_sync_master_enabled=1

Defensive patterns

Strategy: validation

Validate before calling

qr, err := mysqld.FetchSuperQuery(ctx, "SHOW VARIABLES LIKE 'rpl_semi_sync%'")
if err != nil || len(qr.Rows) == 0 {
    log.Warn("semi-sync plugin not loaded; cannot enable semi-sync")
}

Try / catch

err := mysqld.SetSemiSyncEnabled(ctx, true, true)
if err != nil && strings.Contains(err.Error(), "can't set semi-sync mode") {
    log.Error("semi-sync plugin missing; load semisync plugins in my.cnf", slog.Any("error", err))
}

Prevention

Include plugin-load-add for semisync in all my.cnf templates
Verify rpl_semi_sync variables exist after each MySQL upgrade
Use MariaDB-specific variable names when running MariaDB

When it happens

Trigger: Calling mysqld.SetSemiSyncEnabled(...) when the rpl_semi_sync_master/replica plugin is not loaded, so the system variables don't exist and the SET statement fails with ER_UNKNOWN_SYSTEM_VARIABLE.

Common situations: Fresh MySQL installs without semi-sync plugins configured; MariaDB where plugin variable names differ (rpl_semi_sync_master vs rpl_semi_sync_source); my.cnf missing plugin-load lines.

Related errors

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