tablet %s type has changed from %s to %s, restarting vstream

Error message

tablet %s type has changed from %s to %s, restarting vstream

What it means

While streaming health, if shr.Target.TabletType differs from the tablet type the VStreamer initially selected, it errors 'tablet %s type has changed from %s to %s, restarting vstream'. This is intentional fail-fast behavior: the stream was opened against, say, a REPLICA, but the tablet changed type (e.g. promoted or repurposed), so the stream must restart to pick a valid source.

Source

Thrown at go/vt/vtgate/vstream_manager.go:735

			Cell:       vs.vsm.cell,
		}
		tabletConn, err := vs.vsm.resolver.GetGateway().QueryServiceByAlias(ctx, tablet.Alias, target)
		if err != nil {
			log.Error(err.Error())
			return vterrors.Wrapf(err, "failed to get tablet connection to %s", tabletAliasString)
		}

		errCh := make(chan error, 1)
		go func() {
			_ = tabletConn.StreamHealth(ctx, func(shr *querypb.StreamHealthResponse) error {
				var err error
				switch {
				case ctx.Err() != nil:
					err = vterrors.Wrapf(ctx.Err(), "context ended while streaming tablet health from %s", tabletAliasString)
				case shr == nil || shr.RealtimeStats == nil || shr.Target == nil:
					err = fmt.Errorf("health check failed on %s", tabletAliasString)
				case vs.tabletType != shr.Target.TabletType:
					err = fmt.Errorf("tablet %s type has changed from %s to %s, restarting vstream",
						topoproto.TabletAliasString(tablet.Alias), vs.tabletType, shr.Target.TabletType)
				case shr.RealtimeStats.HealthError != "":
					err = fmt.Errorf("tablet %s is no longer healthy: %s, restarting vstream",
						topoproto.TabletAliasString(tablet.Alias), shr.RealtimeStats.HealthError)
				case shr.RealtimeStats.ReplicationLagSeconds > uint32(discovery.GetLowReplicationLag().Seconds()):
					err = fmt.Errorf("tablet %s has a replication lag of %d seconds which is beyond the value provided in --discovery_low_replication_lag of %s so the tablet is no longer considered healthy, restarting vstream",
						topoproto.TabletAliasString(tablet.Alias), shr.RealtimeStats.ReplicationLagSeconds, discovery.GetLowReplicationLag())
				}
				if err != nil {
					log.Warn(fmt.Sprintf("Tablet state changed: %s, attempting to restart", err))
					err = vterrors.Wrapf(err, "error streaming tablet health from %s", tabletAliasString)
					errCh <- err
					return err
				}
				return nil
			})
		}()

View on GitHub (pinned to 01a25a7d17)

Solutions

Let the vstream restart — it re-selects a tablet of the required type automatically.
Check tablet history (vtctldclient GetTablets) to see what changed the type.
If a failover occurred, verify replication caught up and the workflow resumed (copy_state / VReplication status).
Avoid changing tablet types during active VReplication migrations; pause workflows (VReplicationExec pause) first.
If a tablet flaps types repeatedly, fix the automation or reparent loop causing it.

Example fix

// before: promote replica mid-migration
vtctldclient PlannedReparentShard ... # while MoveTables runs → type-change error
// after
vtctldclient VReplicationExec pause; vtctldclient PlannedReparentShard ...; vtctldclient VReplicationExec resume

Defensive patterns

Strategy: retry

Validate before calling

// before migrations, pin tablet types:
// vtctldclient GetTablets → ensure no pending reparent/type change scheduled
// check serving graph: vtctldclient GetSrvVSchema

Try / catch

if err != nil && strings.Contains(err.Error(), "type has changed") {
    // expected during failover: re-select source tablet and restart
    return restartVStreamWithNewSource(ctx)
}

Prevention

Don't run failovers concurrently with VReplication workflows
Pause workflows during planned type changes
Use PRS with workflows paused
Alert on tablet_type flapping

When it happens

Trigger: A tablet reparent/promotion or TabletType change (replica<->rdonly, serving->primary) occurs mid-vstream; vtctldclient SetWritable/ChangeTabletType issued while MoveTables/Reshard is running.

Common situations: Running Reshard/MoveTables concurrent with a failover; automation resharding rdonly tablets; DR switchover during an ongoing migration.

Related errors

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