CopySchemaShard failed because schemas could not be compared

Error message

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

What it means

With verification enabled (skipVerify false), CopySchemaShard calls schematools.CompareSchemas between source and destination tablets after copying. If the comparison RPC itself errors (rather than returning diffs), this error is thrown - the copy status is unknown because final validation could not run.

Source

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

				" Full error: %v", err)
		}
	}

	// Remember the replication position after all the above were applied.
	destPrimaryPos, err := wr.tmc.PrimaryPosition(ctx, destTabletInfo.Tablet)
	if err != nil {
		return fmt.Errorf("CopySchemaShard: can't get replication position after schema applied: %v", err)
	}

	// Although the copy was successful, we have to verify it to catch the case
	// where the database already existed on the destination, but with different
	// options e.g. a different character set.
	// In that case, MySQL would have skipped our CREATE DATABASE IF NOT EXISTS
	// statement.
	if !skipVerify {
		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 finally: %v", err)
		}
		if diffs != nil {
			return fmt.Errorf("CopySchemaShard was not successful because the schemas between the two tablets %v and %v differ: %v", sourceTabletAlias, destShardInfo.PrimaryAlias, diffs)
		}
	}

	// Notify Replicas to reload schema. This is best-effort.
	reloadCtx, cancel := context.WithTimeout(ctx, waitReplicasTimeout)
	defer cancel()
	resp, err := wr.VtctldServer().ReloadSchemaShard(reloadCtx, &vtctldatapb.ReloadSchemaShardRequest{
		Keyspace:       destKeyspace,
		Shard:          destShard,
		WaitPosition:   destPrimaryPos,
		Concurrency:    10,
		IncludePrimary: true,
	})
	if resp != nil {
		for _, e := range resp.Events {

View on GitHub (pinned to 01a25a7d17)

Solutions

Retry CopySchemaShard; the copy is idempotent aside from the table-exists conflict case.
Run GetSchema on both tablets and diff manually to confirm state.
Rerun with skipVerify only as a last resort after manual verification.

Defensive patterns

Strategy: retry

Validate before calling

_, err := schematools.CompareSchemas(ctx, ts, tmc, src, dst, tables, excl, incl)
if err != nil {
    return fmt.Errorf("pre-check comparison failed: %v", err)
}

Try / catch

err := wr.CopySchemaShard(ctx, src, dst, tables, excl, false)
if err != nil && strings.Contains(err.Error(), "could not be compared") {
    // verify tablets reachable, retry
}

Prevention

Pre-check that both tablets answer GetSchema before copying.
Run schema copies during low-load windows.
Retry transient RPC failures automatically.

When it happens

Trigger: CompareSchemas fails because the source or destination tablet's GetSchema RPC fails during verification, or the destination primary was unreachable immediately after the copy phase.

Common situations: Network blip right after schema application; destination tablet restarted; topo/tabletmanager timeouts during long schema copies.

Related errors

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