vitessio/vitess · error

CreateShard(%v:%v) failed: %v

Error message

CreateShard(%v:%v) failed: %v

What it means

CreateKs creates each shard in the keyspace via ts.CreateShard; topo-level failures are wrapped as 'CreateShard(<keyspace>:<shard>) failed'. Like CreateKeyspace failure, it indicates the shard record could not be created in the topo server.

Source

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

	srvTopoCounts *stats.CountersWithSingleLabel,
) (uint32, error) {
	keyspace := kpb.Name

	// create a regular keyspace
	if err := ts.CreateKeyspace(ctx, keyspace, &topodatapb.Keyspace{}); err != nil {
		return 0, fmt.Errorf("CreateKeyspace(%v) failed: %v", keyspace, err)
	}

	// make sure a valid vschema has been loaded
	if err := ts.EnsureVSchema(ctx, keyspace); err != nil {
		return 0, fmt.Errorf("EnsureVSchema(%v) failed: %v", keyspace, err)
	}

	// iterate through the shards
	for _, spb := range kpb.Shards {
		shard := spb.Name
		if err := ts.CreateShard(ctx, keyspace, shard); err != nil {
			return 0, fmt.Errorf("CreateShard(%v:%v) failed: %v", keyspace, shard, err)
		}

		for _, cell := range tpb.Cells {
			dbname := spb.DbNameOverride
			if dbname == "" {
				dbname = fmt.Sprintf("vt_%v_%v", keyspace, shard)
			}

			replicas := int(kpb.ReplicaCount)
			if replicas == 0 {
				// 2 replicas in order to ensure the primary cell has a primary and a replica
				replicas = 2
			}
			rdonlys := int(kpb.RdonlyCount)
			if rdonlys == 0 {
				rdonlys = 1
			}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check if the shard already exists (vtctldclient GetShard <ks>/<shard>) and skip or clean up before re-running.
2. Validate shard names in the Keyspace proto are well-formed keyranges (e.g. '-', '-80', '80-', 'c0-') for sharded keyspaces.
3. Verify topo server health and permissions, then retry CreateKs after removing partial keyspace state.

Example fix

// before (duplicate shard create)
CreateShard(ctx, "commerce", "0") // already exists
// after
if _, err := ts.GetShard(ctx, "commerce", "0"); err != nil {
    CreateShard(ctx, "commerce", "0")
}

// Go: skip existing shards
if _, err := ts.GetShard(ctx, keyspace, shard); err == nil {
    continue // shard already exists
}

if _, err := CreateKs(...); err != nil {
    if strings.Contains(err.Error(), "CreateShard") {
        // check shard name validity and pre-existing shard; clean partial state before retry
    }
}

When it happens

Trigger: CreateKs iterating kpb.Shards where ts.CreateShard(ctx, keyspace, shard) errors: shard already exists, topo server unreachable, or invalid shard name/keyrange.

Common situations: Re-running initialization against a topo that already has the shard; invalid shard names (e.g. bad hex keyrange like '-80' vs '80-'); concurrent creation of the same shard by another process; etcd/zk outage.

Related errors

• shard not found
• no primary tablet found
• failed to get shard %s/%s: %v
• shard %s/%s has no primary
• RebuildVSchemaGraph failed: %v

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