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

Raised when a pull merge produced rows in dolt_constraint_violations and bd's automatic repair (tryRepairFKCascadeViolations) could not fully clear them. bd refuses to commit any state that still contains constraint violations, rolls the transaction back, and returns this error so the user resolves the violations manually before retrying.

Source

Thrown at internal/storage/dolt/store.go:4474

	}

	// bd-6dnrw.4: repair FK cascade violations the merge produced (child rows
	// whose parent issue was deleted on the other clone). Unrepaired
	// violations MUST NOT be committed.
	repairedViol, hadViol, violErr := s.tryRepairFKCascadeViolations(ctx, tx)
	if violErr != nil {
		_ = tx.Rollback()
		if pullErr != nil {
			return pullErr
		}
		return violErr
	}
	if hadViol && !repairedViol {
		_ = tx.Rollback()
		if pullErr != nil {
			return pullErr
		}
		return fmt.Errorf("pull merge left constraint violations bd cannot auto-repair; inspect dolt_constraint_violations and resolve before retrying")
	}

	if pullErr != nil && !resolved && !repairedViol {
		// Pull failed for a non-conflict reason, or conflicts include non-metadata tables.
		_ = tx.Rollback()
		return pullErr
	}

	// 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).
	if resolved {
		if err := versioncontrolops.CommitResolvedConflicts(ctx, tx); err != nil {
			_ = tx.Rollback()
			if pullErr != nil {
				return pullErr
			}
			return err

View on GitHub (pinned to 71377f2769)

Solutions

1. Query dolt_constraint_violations to see the offending rows: `SELECT * FROM dolt_constraint_violations;`
2. Resolve each violation manually (delete or correct the conflicting dependency/issue rows)
3. Clear resolved entries from dolt_constraint_violations
4. Re-run `bd dolt pull` to complete the merge
5. If violations recur from a specific clone, reconcile that clone's data before pulling

// Before retrying the pull, confirm violations are cleared
rows, err := db.Query("SELECT COUNT(*) FROM dolt_constraint_violations")
// count must be 0 before retrying

if err := store.Pull(ctx); err != nil {
    if strings.Contains(err.Error(), "constraint violations bd cannot auto-repair") {
        // inspect and resolve manually, then retry
        // SELECT * FROM dolt_constraint_violations;
        return fmt.Errorf("manual resolution required: %w", err)
    }
    return err
}

When it happens

Trigger: A `bd dolt pull` merges remote commits whose foreign-key/dependency rows conflict with local rows in a way the built-in cascade repair does not cover — e.g. both sides edited the same dependency edge with incompatible cascade semantics.

Common situations: Two clones concurrently edited the same issue's dependencies (a dependency deleted locally but modified remotely); merge of divergent blocked-status data; schema-version skew between clones producing rows the repair rules don't recognize.

Related errors

• conflicts resolved with '%s' strategy but merge left constra
• failed to commit pending changes before pull: %w
• merge failed: %w
• merge succeeded but is_blocked recompute failed: %w
• acquire connection for merge: %w

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