vitessio/vitess · error

unexpected error: cannot find diff: %v

Error message

unexpected error: cannot find diff: %v

What it means

OrderedDiffs reorders an EntityDiff set by looking up each statement string produced by OrderedClasses() in the diff set's internal map. If a class's statement cannot be found, this internal-consistency error is returned. It almost always signals a bug in schemadiff or use of an API against a stale/partially constructed diff object, not a user schema problem.

Source

Thrown at go/vt/schemadiff/schema_diff.go:379

			ConflictingDiffs: d.UnorderedDiffs(),
		}
	}
	lastGoodSchema := d.schema.copy()
	var orderedDiffs []EntityDiff
	m := d.r.Map()

	unorderedDiffsMap := map[string]int{}
	for i, diff := range d.UnorderedDiffs() {
		unorderedDiffsMap[diff.CanonicalStatementString()] = i
	}
	// The order of classes in the equivalence relation is, generally speaking, loyal to the order of original diffs.
	for _, class := range d.r.OrderedClasses() {
		classDiffs := []EntityDiff{}
		// Which diffs are in this equivalence class?
		for _, statementString := range m[class] {
			diff, ok := d.diffByStatementString(statementString)
			if !ok {
				return nil, fmt.Errorf("unexpected error: cannot find diff: %v", statementString)
			}
			classDiffs = append(classDiffs, diff)
		}
		sort.SliceStable(classDiffs, func(i, j int) bool {
			return unorderedDiffsMap[classDiffs[i].CanonicalStatementString()] < unorderedDiffsMap[classDiffs[j].CanonicalStatementString()]
		})

		// We will now permutate the diffs in this equivalence class, and hopefully find
		// a valid permutation (one where if we apply the diffs in-order, the schema remains valid throughout the process)
		tryPermutateDiffs := func(hints *DiffHints) (bool, error) {
			return permutateDiffs(ctx, classDiffs, hints, func(permutatedDiffs []EntityDiff, hints *DiffHints) (bool, int) {
				permutationSchema := lastGoodSchema.copy()
				// We want to apply the changes one by one, and validate the schema after each change
				for i := range permutatedDiffs {
					// apply inline
					applyHints := hints
					if hints.ForeignKeyCheckStrategy == ForeignKeyCheckStrategyCreateTableFirst {
						// This is a strategy that handles foreign key loops in a heuristic way.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Re-run the diff generation from scratch so the diff set and ordering groups come from the same run
2. If reproducible, file a vitess bug with the schemas and diff output — this is an internal invariant violation
3. Upgrade to a newer vitess version where normalization/canonicalization bugs may be fixed

Example fix

// before: reusing a stale diff object across schema versions
ordered, err := staleDiff.OrderedDiffs()
// after
freshDiff, err := schemaDiff.FromSchemas(ctx, from, to)
ordered, err := freshDiff.OrderedDiffs()

ordered, err := diff.OrderedDiffs()
if err != nil {
  if strings.Contains(err.Error(), "cannot find diff") {
    // regenerate the diff from scratch and retry once
  }
}

When it happens

Trigger: Calling OrderedDiffs where m[class] contains a statement string for which d.diffByStatementString returns !ok — i.e. the class grouping and the diff map are out of sync.

Common situations: Custom tooling consuming schemadiff internals against a modified or cached diff; a genuine schemadiff defect in grouping/canonicalization (e.g. canonical statement string mismatch after normalization changes).

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• mismatched entity type
• strict index ordering is unsupported
• unexpected diff action
• unexpected table spec
• expected a CREATE TABLE statement

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