What causes "no source shards specified for workflow %s " in vitessio/vitess?

Check shard names with `vtctl GetShardNames ` and fix the source shard specification

no source shards specified for workflow %s

Error message

no source shards specified for workflow %s

What it means

buildMaterializer requires at least one source shard to stream from. After applying any shard filter (ms.SourceShards), if the resulting list is empty, the workflow cannot be built, so this error is returned. It prevents creating a vreplication stream with no source.

Source

Thrown at go/vt/vtctl/workflow/materializer.go:517

		}
	}
	isPartial := false
	sourceShards, err := mz.sourceTs.GetServingShards(ctx, ms.SourceKeyspace)
	if err != nil {
		return err
	}
	if len(ms.SourceShards) > 0 {
		isPartial = true
		var sourceShards2 []*topo.ShardInfo
		for _, shard := range sourceShards {
			if slices.Contains(ms.SourceShards, shard.ShardName()) {
				sourceShards2 = append(sourceShards2, shard)
			}
		}
		sourceShards = sourceShards2
	}
	if len(sourceShards) == 0 {
		return fmt.Errorf("no source shards specified for workflow %s ", ms.Workflow)
	}

	targetShards, err := mz.ts.GetServingShards(ctx, ms.TargetKeyspace)
	if err != nil {
		return err
	}

	// For a multi-tenant migration, user can specify a subset of target shards to stream to, based
	// on the vindex they have chosen. This is to optimize the number of streams: for example, if we
	// have 256 shards and a tenant maps to a single shard we can avoid creating 255 unnecessary streams
	// that would be filtered out by the vindex anyway.
	var specifiedTargetShards []string
	switch {
	case mz.IsMultiTenantMigration():
		specifiedTargetShards = ms.WorkflowOptions.Shards
	case len(ms.SourceShards) > 0: // shard-by-shard migration
		specifiedTargetShards = ms.SourceShards
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

Check shard names with `vtctl GetShardNames <keyspace>` and fix the source shard specification
Omit the source-shards filter to use all shards of the source keyspace
Verify the source keyspace name is correct and has serving shards

Example fix

// before
CreateWorkflow --source-keyspace=commerce --source-shards=bad-shard
// after
CreateWorkflow --source-keyspace=commerce --source-shards=0-�00000000

Defensive patterns

Strategy: validation

Validate before calling

shards, err := ts.GetShardNames(ctx, sourceKeyspace)
if err != nil { return err }
for _, s := range requestedSourceShards {
    if !slices.Contains(shards, s) {
        return fmt.Errorf("source shard %q not in keyspace %s", s, sourceKeyspace)
    }
}

Try / catch

if err := createWorkflow(ctx, req); err != nil {
    if strings.Contains(err.Error(), "no source shards specified") {
        // fix --source-shards using GetShardNames output
    }
    return err
}

Prevention

Fetch shard names via GetShardNames instead of hardcoding them
Use the standard '0-' or range formats produced by the topo
Omit source-shards filters when you want all shards

When it happens

Trigger: createWorkflowStreams or WorkflowAddTables builds a materializer where ms.SourceShards was specified but matched no shards, or the computed source shard list ends up empty after filtering.

Common situations: --source-shards flag with an invalid shard name that matches nothing; empty shard set on the source keyspace; shard names not matching topo naming convention (e.g. '-' vs '/'); source keyspace typo.

Related errors

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