vitessio/vitess · error

cannot migrate streams with a mix of reference and sharded t

Error message

cannot migrate streams with a mix of reference and sharded tables: %v

What it means

During templatize (part of stream migration), each filter rule of a stream is classified as StreamTypeSharded or StreamTypeReference via templatizeRule. This error is thrown when a sharded-typed stream also contains rules for reference (non-sharded) tables — a stream mixing both kinds cannot be templatized into per-shard keyrange templates and migrated. This is the first of the two symmetric check sites (sharded encountered while stream was already reference).

Source

Thrown at go/vt/vtctl/workflow/stream_migrator.go:1091

/* templatizing */

func (sm *StreamMigrator) templatize(ctx context.Context, tabletStreams []*VReplicationStream) ([]*VReplicationStream, error) {
	var shardedStreams []*VReplicationStream

	tabletStreams = VReplicationStreams(tabletStreams).Copy().ToSlice()
	for _, vrs := range tabletStreams {
		streamType := StreamTypeUnknown

		for _, rule := range vrs.BinlogSource.Filter.Rules {
			typ, err := sm.templatizeRule(ctx, rule)
			if err != nil {
				return nil, err
			}

			switch typ {
			case StreamTypeSharded:
				if streamType == StreamTypeReference {
					return nil, fmt.Errorf("cannot migrate streams with a mix of reference and sharded tables: %v", vrs.BinlogSource)
				}
				streamType = StreamTypeSharded
			case StreamTypeReference:
				if streamType == StreamTypeSharded {
					return nil, fmt.Errorf("cannot migrate streams with a mix of reference and sharded tables: %v", vrs.BinlogSource)
				}
				streamType = StreamTypeReference
			}
		}

		if streamType == StreamTypeSharded {
			shardedStreams = append(shardedStreams, vrs)
		}
	}

	return shardedStreams, nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Split the workflow: keep sharded tables in one vreplication workflow and reference tables in a separate one, then migrate each separately.
2. Move reference-table replication out of the stream being migrated (e.g. cancel those rules or use a dedicated reference-tables workflow).
3. Check whether a table type changed (`show vitess_keyspaces` / vschema): if a table was recently converted to a reference table, recreate the workflow consistent with the new type.
4. Re-run the migration with a filter containing only same-type tables.

Example fix

// before: one workflow with rules for sharded 'user' and reference 'product'
// after: two workflows
// workflowA: filter rules for sharded tables only
// workflowB: filter rules for reference tables only (migrated separately)

// Before migrating, check each workflow's tables resolve to a single type
// in the vschema: all sharded OR all reference.
// SHOW VSCHEMA TABLES; -> classify each filtered table by vindex type

When it happens

Trigger: Calling BuildStreamMigrator / StopStreams / LegacyStopStreams where a workflow's BinlogSource.Filter contains rules whose tables resolve to both vindexes.TypeReference and sharded types, with a reference-type rule appearing after (or while) a sharded rule set streamType=Sharded... precisely: a sharded-typed rule is processed after a reference-typed rule (streamType==Reference) — wait, line 1091 fires when a StreamTypeSharded rule arrives while streamType is Reference; line 1096 is its mirror.

Common situations: A MoveTables or Materialize workflow was configured to replicate both sharded tables and reference tables in one stream; a table's vindex type changed (converted to reference table) after the workflow started; user added a reference table to an existing sharded workflow's filter.

Related errors

• table %v not found in vschema
• both atomic copy and partial mode cannot be specified for th
• invalid workflow
• multiple source keyspaces for a single workflow
• multiple target keyspaces for a single workflow

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