gastownhall/beads · error

pull merge left constraint violations bd cannot auto-repair;

Error message

pull merge left constraint violations bd cannot auto-repair; inspect dolt_constraint_violations and resolve before retrying

What it means

After resolving conflicts, SettleMerge attempts to repair FK cascade violations (child rows referencing issues deleted on another clone). This error is returned when violations exist (hadViol=true) but none could be repaired (repairedViol=false) — i.e. the violations have a shape bd cannot handle (non-FK type, unknown table, FK to a parent other than issues). The merge is aborted so no violated working set is committed.

Source

Thrown at internal/storage/versioncontrolops/mergesettle.go:197

	// whose parent issue was deleted on the other clone). Unrepaired
	// violations MUST NOT survive: with the force flag on, every statement
	// autocommits, so the abort below is what keeps them out of the database.
	// This also covers violations a strategy resolution left behind (e.g.
	// --ours keeps a child row whose parent was deleted on the other side).
	repairedViol, hadViol, violErr := TryRepairFKCascadeViolations(ctx, db)
	if violErr != nil {
		abortMerge(ctx, db, preMergeClean)
		if mergeErr != nil {
			return mergeErr
		}
		return violErr
	}
	if hadViol && !repairedViol {
		abortMerge(ctx, db, preMergeClean)
		if mergeErr != nil {
			return mergeErr
		}
		return fmt.Errorf("pull merge left constraint violations bd cannot auto-repair; inspect dolt_constraint_violations and resolve before retrying")
	}

	if mergeErr != nil && !resolved && !strategyResolved && !repairedViol {
		// Merge failed for a non-conflict reason, or conflicts include non-metadata tables.
		abortMerge(ctx, db, preMergeClean)
		return mergeErr
	}

	// Conclude the merge for resolved conflicts only now, after the FK repair:
	// DOLT_COMMIT refuses a violated working set, so a merge carrying both
	// classes could never settle when the resolver committed first (bd-578h9.14).
	switch {
	case resolved:
		if err := CommitResolvedConflicts(ctx, db); err != nil {
			abortMerge(ctx, db, preMergeClean)
			if mergeErr != nil {
				return mergeErr
			}

View on GitHub (pinned to 71377f2769)

Solutions

1. Re-open the database and query `SELECT * FROM dolt_constraint_violations` plus the per-table dolt_constraint_violations_<table> tables to see exactly what violates
2. Resolve manually: delete or restore the offending rows, clear the violations tables, then retry the pull
3. Check for schema forks — verify both clones run the same bd version and applied the same migrations (bd doctor reports Migration Content Skew)
4. If violations are a legit issues-FK cascade case, upgrade bd — newer versions extend the repair allowlist

Example fix

// after a failed pull, inspect manually:
// SELECT `table`, num_violations FROM dolt_constraint_violations WHERE num_violations > 0;
// SELECT * FROM dolt_constraint_violations_dependencies;
// delete dangling rows, then:
err := versioncontrolops.MergeAndSettle(ctx, db, ref)

// before pulling, check schema consistency across clones (same bd version + migrations)
// bd doctor reports Migration Content Skew; also pre-check existing violations:
rows, _ := db.QueryContext(ctx, "SELECT `table` FROM dolt_constraint_violations WHERE num_violations > 0")
// any rows here mean an earlier merge left state the pull cannot auto-repair

func isUnrepairableViolations(err error) bool {
	return strings.Contains(err.Error(), "constraint violations bd cannot auto-repair")
}

err := versioncontrolops.MergeAndSettle(ctx, db, ref)
if err != nil && isUnrepairableViolations(err) {
	// operator path: inspect dolt_constraint_violations, delete/restore rows manually,
	// clear the violations tables, then retry the pull
	return fmt.Errorf("manual constraint repair required: %w", err)
}

When it happens

Trigger: A pull/merge whose result leaves constraint violations outside the known issues-FK cascade class: unique-key violations, FKs to non-issues parents, or violations on tables not in the repair allowlist.

Common situations: Two clones where one deleted an issue and the other added rows referencing it via a schema bd does not recognize; a schema extension adding custom FKs; mixed bd versions with divergent schemas.

Related errors

• failed to commit resolved conflicts: %w
• failed to get conflicts: %w
• failed to scan conflict: %w
• pull merge left constraint violations bd cannot auto-repair;
• creating wisp_dependencies for migration 0047: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/6c32c873032e9446. Report an issue: GitHub.