vitessio/vitess · error

TabletExternallyReparented failed on primary %v: %v

Error message

TabletExternallyReparented failed on primary %v: %v

What it means

In vtcombo (vitess local/test combo), CreateTablet promotes a tablet to PRIMARY by calling tm.ChangeType(ctx, TabletType_PRIMARY, semi-sync=false). Failure is wrapped as 'TabletExternallyReparented failed on primary'. It signals the tablet manager could not switch the tablet's MySQL/tablet state to primary.

Source

Thrown at go/vt/vtcombo/tablet_map.go:133

		Alias: alias,
		PortMap: map[string]int32{
			"vt":   int32(8000 + uid),
			"grpc": int32(9000 + uid),
		},
		Keyspace:       keyspace,
		Shard:          shard,
		KeyRange:       kr,
		Type:           initTabletType,
		DbNameOverride: dbname,
	}
	if err := tm.Start(tablet, nil); err != nil {
		return err
	}

	if tabletType == topodatapb.TabletType_PRIMARY {
		// Semi-sync has to be set to false, since we have 1 single backing MySQL
		if err := tm.ChangeType(ctx, topodatapb.TabletType_PRIMARY /* semi-sync */, false); err != nil {
			return fmt.Errorf("TabletExternallyReparented failed on primary %v: %v", topoproto.TabletAliasString(alias), err)
		}
	}
	controller.AddStatusHeader()
	controller.AddStatusPart()
	tabletMap[uid] = &comboTablet{
		alias:      alias,
		keyspace:   keyspace,
		shard:      shard,
		tabletType: tabletType,
		dbname:     dbname,
		uid:        uid,

		qsc: controller,
		tm:  tm,
	}
	return nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check mysqld status for the tablet uid (ps/logs under $VTDATAROOT/vt_0000000001/) and ensure it is fully started before creating a PRIMARY tablet.
2. Inspect the tablet's tabletmanager logs for the underlying ChangeType error and address it (e.g. replication not configured, semi-sync plugin issues).
3. Re-run vtcombo/tablet creation after cleanup (vtctldclient DeleteTablet or removing the topo entry) if a stale primary exists.

Example fix

// before (create PRIMARY tablet before mysqld ready)
CreateTablet(ctx, ts, tmc, cell, uid, topodatapb.TabletType_PRIMARY)
// after
waitForMysqld(uid) // ensure mysqld is healthy first
CreateTablet(ctx, ts, tmc, cell, uid, topodatapb.TabletType_PRIMARY)

// Go: ensure mysqld is up before creating a PRIMARY tablet
if err := mysqlctl.WaitForMysqld(ctx, tabletDir, uid, 30*time.Second); err != nil {
    return fmt.Errorf("mysqld not ready for uid %d: %w", uid, err)
}

if err := CreateTablet(...); err != nil {
    if strings.Contains(err.Error(), "TabletExternallyReparented failed") {
        // check tablet logs; wait for mysqld; retry with backoff
    }
}

When it happens

Trigger: Creating a tablet with type PRIMARY in vtcombo when tm.ChangeType fails: backing mysqld not running/healthy, tablet manager RPC failure, or semi-sync configuration conflict on the single shared MySQL instance.

Common situations: Local vitess (vitess-local) environment where mysqld for the tablet isn't up yet or crashed; another tablet already claims primary on the shard; mysqlctl startup still in progress when CreateTablet runs.

Related errors

• no primary tablet found
• can't get primary replication position: %v
• creating this tablet would override old primary %v in shard
• cannot find tablet: %+v
• tablet %v ResetReplication failed (either fix it, or Scrap i

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