vitessio/vitess · error

CopySchemaShard failed because schemas could not be compared

Error message

CopySchemaShard failed because schemas could not be compared initially: %v

What it means

CopySchemaShard starts by comparing the source tablet's schema with the destination primary's schema via schematools.CompareSchemas. This error is returned when that initial comparison fails — either side's GetSchema RPC failed, a tablet was unreachable, or the comparison itself errored. It deliberately aborts before attempting any copy, so no schema changes have been applied when this is raised.

Source

Thrown at go/vt/wrangler/schema.go:215

}

// CopySchemaShard copies the schema from a source tablet to the
// specified shard.  The schema is applied directly on the primary of
// the destination shard, and is propagated to the replicas through
// binlogs.
func (wr *Wrangler) CopySchemaShard(ctx context.Context, sourceTabletAlias *topodatapb.TabletAlias, tables, excludeTables []string, includeViews bool, destKeyspace, destShard string, waitReplicasTimeout time.Duration, skipVerify bool) error {
	destShardInfo, err := wr.ts.GetShard(ctx, destKeyspace, destShard)
	if err != nil {
		return fmt.Errorf("GetShard(%v, %v) failed: %v", destKeyspace, destShard, err)
	}

	if destShardInfo.PrimaryAlias == nil {
		return fmt.Errorf("no primary in shard record %v/%v. Consider running 'vtctl InitShardPrimary' in case of a new shard or reparenting the shard to fix the topology data", destKeyspace, destShard)
	}

	diffs, err := schematools.CompareSchemas(ctx, wr.ts, wr.tmc, sourceTabletAlias, destShardInfo.PrimaryAlias, tables, excludeTables, includeViews)
	if err != nil {
		return fmt.Errorf("CopySchemaShard failed because schemas could not be compared initially: %v", err)
	}
	if diffs == nil {
		// Return early because dest has already the same schema as source.
		return nil
	}

	req := &tabletmanagerdatapb.GetSchemaRequest{Tables: tables, ExcludeTables: excludeTables, IncludeViews: includeViews}
	sourceSd, err := schematools.GetSchema(ctx, wr.ts, wr.tmc, sourceTabletAlias, req)
	if err != nil {
		return fmt.Errorf("GetSchema(%v, %v, %v, %v) failed: %v", sourceTabletAlias, tables, excludeTables, includeViews, err)
	}

	createSQLstmts := tmutils.SchemaDefinitionToSQLStrings(sourceSd)

	destTabletInfo, err := wr.ts.GetTablet(ctx, destShardInfo.PrimaryAlias)
	if err != nil {
		return fmt.Errorf("GetTablet(%v) failed: %v", destShardInfo.PrimaryAlias, err)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check both tablets' health (vtctl GetTablet on source alias and dest primary) and ensure vttablet is serving.
2. Re-run CopySchemaShard after restoring connectivity — the failure is before any mutation, so it is safe to retry.
3. Inspect the wrapped inner error to determine which side (source vs dest) failed and why.
4. If timeouts are the cause, increase the context deadline or check for network latency between vtctld and tablets.

Example fix

// before (dest primary unreachable)
wr.CopySchemaShard(ctx, srcAlias, nil, nil, true, "ks", "0", timeout, false)
// after: verify tablets then retry
ti, _ := wr.ts.GetTablet(ctx, destPrimaryAlias) // ensure reachable
wr.CopySchemaShard(ctx, srcAlias, nil, nil, true, "ks", "0", timeout, false)

for _, alias := range []*topodatapb.TabletAlias{srcAlias, dstPrimaryAlias} {
	ti, err := ts.GetTablet(ctx, alias)
	if err != nil { return err }
	if ti.State != topodatapb.TabletState_SERVING { return fmt.Errorf("tablet %v not serving", alias) }
}

err := wr.CopySchemaShard(...)
if err != nil && strings.Contains(err.Error(), "could not be compared initially") {
	// safe to retry: nothing was applied; fix tablet health then retry with backoff
	time.Sleep(backoff)
	return wr.CopySchemaShard(...)
}

When it happens

Trigger: Calling CopySchemaShard where the source tablet or destination primary is down/not serving, the tabletmanager GetSchema RPC fails or times out on either side, or CompareSchemas hits an internal error.

Common situations: Source tablet decommissioned between alias resolution and comparison; destination primary restarting; network partition between vtctld and either tablet; version mismatch causing schema parse failures.

Related errors

• can't get primary replication position: %v
• Error setting tablet to read-only: %w
• Error setting tablet to read-write: %w
• GetSchema(%v, nil, %v, %v) failed: %v
• GetVersion(%s) failed: %v

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