vitessio/vitess · error

VReplication streams must have named workflows for migration

Error message

VReplication streams must have named workflows for migration: shard: %s:%s

What it means

During a Reshard-based stream migration, the resharder validates that every VReplication stream on the source shards belongs to a named workflow before it can be migrated to the target keyspace. An unnamed (empty workflow name) stream cannot be tracked or re-targeted by the migration machinery, so the operation fails fast. This is a safety check to avoid orphaning streams during resharding.

Source

Thrown at go/vt/vtctl/workflow/resharder.go:191

		mu.Lock()
		defer mu.Unlock()

		mustCreate := false
		var ref map[string]bool
		if rs.refStreams == nil {
			rs.refStreams = make(map[string]*refStream)
			mustCreate = true
		} else {
			// Copy the ref streams for comparison.
			ref = make(map[string]bool, len(rs.refStreams))
			for k := range rs.refStreams {
				ref[k] = true
			}
		}
		for _, workflow := range res.Workflows {
			if workflow.Workflow == "" {
				return fmt.Errorf("VReplication streams must have named workflows for migration: shard: %s:%s", source.Keyspace(), source.ShardName())
			}
			for _, stream := range workflow.Streams {
				bls := stream.Bls
				isReference, err := rs.blsIsReference(bls)
				if err != nil {
					return vterrors.Wrap(err, "blsIsReference")
				}
				if !isReference {
					continue
				}
				refKey := fmt.Sprintf("%s:%s:%s", workflow.Workflow, bls.Keyspace, bls.Shard)
				if mustCreate {
					rs.refStreams[refKey] = &refStream{
						workflow:        workflow.Workflow,
						bls:             bls,
						cell:            workflow.Cells,
						tabletTypes:     discovery.BuildTabletTypesString(workflow.TabletTypes, workflow.TabletSelectionPreference),
						workflowType:    workflow.WorkflowType,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Identify the unnamed stream on the named shard (SELECT id, workflow FROM _vt.vreplication WHERE workflow='') and delete or name it.
2. If the stream is obsolete, cancel/remove it before retrying the migration.
3. If it is needed, re-create it via a supported workflow (MoveTables/Reshard) so it gets a proper workflow name.
4. Upgrade intermediate Vitess versions so legacy streams are migrated to named workflows.

Example fix

-- before
mysql> SELECT id, workflow FROM _vt.vreplication WHERE workflow='';
-- after (remove or fix the offending row)
mysql> DELETE FROM _vt.vreplication WHERE id=<id>;

-- Run on every source shard before MigrateStreams
SELECT id, shard, workflow FROM _vt.vreplication WHERE workflow = '';

err := vtctldClient.MigrateStreams(...)
if err != nil && strings.Contains(err.Error(), "must have named workflows") {
    // inspect and clean up unnamed streams, then retry
}

When it happens

Trigger: Running MigrateStreams (or a reshard that migrates existing VReplication streams) when at least one vreplication row on a source shard has an empty workflow column — typically streams created by legacy Vitess versions or by manual inserts into _vt.vreplication.

Common situations: Clusters upgraded from very old Vitess versions that predated named workflows; manually created VReplication rows for testing; partial state left by crashed tooling that inserted vreplication rows without a workflow name.

Related errors

• cannot reshard streams with a mix of reference and sharded t
• table %v not found in vschema
• either source or target shards are missing
• validateWorkflowName.VReplicationExec: <dynamic validation.m
• some streams already exist in the target shards, please clea

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