What causes "cannot rebuild %v: %v" in vitessio/vitess?

Inspect the wrapped error for the underlying topo failure and address it (connectivity, permissions).

cannot rebuild %v: %v

Error message

cannot rebuild %v: %v

What it means

After creating tablets and the vschema, CreateKs calls topotools.RebuildKeyspace to regenerate the serving SrvKeyspace object in the topo server. This error means that rebuild failed — typically the topo update failed or no tablets were available to derive serving graph data.

Source

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

			if err != nil {
				return 0, fmt.Errorf("BuildKeyspace(%v) failed: %v", keyspace, err)
			}
			ksvs := &topo.KeyspaceVSchemaInfo{
				Name:     keyspace,
				Keyspace: formal,
			}
			if err := ts.SaveVSchema(ctx, ksvs); err != nil {
				return 0, fmt.Errorf("SaveVSchema(%v) failed: %v", keyspace, err)
			}
		} else {
			log.Info(fmt.Sprintf("File %v doesn't exist, skipping vschema for keyspace %v", f, keyspace))
		}
	}

	// Rebuild the SrvKeyspace object, so we can support
	// range-based sharding queries, and export the redirects.
	if err := topotools.RebuildKeyspace(ctx, wr.Logger(), wr.TopoServer(), keyspace, nil, false); err != nil {
		return 0, fmt.Errorf("cannot rebuild %v: %v", keyspace, err)
	}
	return uid, nil
}

//
// TabletConn implementation
//

// dialer is our tabletconn.Dialer
func dialer(ctx context.Context, tablet *topodatapb.Tablet, failFast grpcclient.FailFast) (queryservice.QueryService, error) {
	t, ok := tabletMap[tablet.Alias.Uid]
	if !ok {
		return nil, vterrors.New(vtrpcpb.Code_UNAVAILABLE, "connection refused")
	}

	return &internalTabletConn{
		tablet:     t,
		topoTablet: tablet,

View on GitHub (pinned to 01a25a7d17)

Solutions

Inspect the wrapped error for the underlying topo failure and address it (connectivity, permissions).
Re-run vtctldclient RebuildKeyspaceGraph for the affected keyspace/cells once topo is healthy.
Verify tablets were created correctly (list them in topo) — re-run InitTabletMap if partial.
Ensure the primary tablet creation step succeeded; a missing primary can break serving expectations.
Restart vtcombo init in a clean state if topo data is inconsistent.

Example fix

// manual recovery after failure
vtctldclient RebuildKeyspaceGraph --cells=cell1 commerce

Defensive patterns

Strategy: retry

Validate before calling

// ensure the keyspace and tablets exist in topo before rebuild
if _, err := ts.GetKeyspace(ctx, keyspace); err != nil {
	return fmt.Errorf("keyspace missing from topo: %w", err)
}
tablets, err := ts.GetTabletsByCell(ctx, cell, nil)
if err != nil || len(tablets) == 0 {
	return fmt.Errorf("no tablets available for rebuild in cell %s", cell)
}

Try / catch

err := CreateKs(...)
if err != nil && strings.Contains(err.Error(), "cannot rebuild") {
	// manual or automatic recovery
	_ = vtctldclient.Run("RebuildKeyspaceGraph", "--cells="+cell, keyspace)
}

Prevention

Confirm earlier CreateKs steps (tablet creation, primary election) succeeded before rebuilding
Check topo server health on rebuild failures
Use RebuildKeyspaceGraph manually to recover from partial failures
Avoid concurrent init of the same keyspace

When it happens

Trigger: CreateKs completing tablet creation but failing RebuildKeyspace: topo server write failure, keyspace/cell missing from topo, inconsistent tablet records (e.g. primary tablet creation failed earlier), or context cancellation during rebuild.

Common situations: Partial InitTabletMap failure leaving tablets half-registered; etcd/zk outage during rebuild; concurrent operations rebuilding the same keyspace; vtcombo shutdown mid-init.

Related errors

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