gastownhall/beads · error

query constraint violations: %w

Error message

query constraint violations: %w

What it means

constraintViolationTables enumerates tables with outstanding constraint violations by querying dolt_constraint_violations. If the query itself fails, this error is returned. It typically means the violations system table is unavailable or the query is rejected by the engine.

Source

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

	// deletes above did not cover the constraint that fired, and committing
	// would persist a violated working set.
	remaining, err := constraintViolationTables(ctx, db)
	if err != nil {
		return false, true, err
	}
	if len(remaining) > 0 {
		return false, true, nil
	}
	return true, true, nil
}

// constraintViolationTables lists the tables with outstanding constraint
// violations in the working set.
func constraintViolationTables(ctx context.Context, db DBConn) ([]string, error) {
	rows, err := db.QueryContext(ctx,
		"SELECT `table` FROM dolt_constraint_violations WHERE num_violations > 0")
	if err != nil {
		return nil, fmt.Errorf("query constraint violations: %w", err)
	}
	defer rows.Close()
	var tables []string
	for rows.Next() {
		var t string
		if err := rows.Scan(&t); err != nil {
			return nil, fmt.Errorf("scan constraint violation: %w", err)
		}
		tables = append(tables, t)
	}
	return tables, rows.Err()
}

// violationsAreIssueFKOnly reports whether every constraint violation recorded
// for table is a foreign-key violation referencing issues — the only class the
// cascade repair understands. violation_info is Dolt's JSON descriptor; its
// ReferencedTable names the FK's parent.
func violationsAreIssueFKOnly(ctx context.Context, db DBConn, table string) (bool, error) {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped %w error: 'table doesn't exist' means no violations or unsupported engine version.
2. Verify Dolt version supports constraint violation tracking (dolt_constraint_violations).
3. Retry after the connection/transaction is healthy; constraint violations only exist after a merge with FK issues.
4. If no merge is in progress, treat absence of the table as 'no violations'.

Example fix

// before
rows, err := db.QueryContext(ctx, "SELECT `table` FROM dolt_constraint_violations WHERE num_violations > 0")
if err != nil {
    return nil, fmt.Errorf("query constraint violations: %w", err)
}
// after: tolerate missing table as zero violations
rows, err := db.QueryContext(ctx, "SELECT `table` FROM dolt_constraint_violations WHERE num_violations > 0")
if err != nil {
    if strings.Contains(err.Error(), "doesn't exist") {
        return nil, nil
    }
    return nil, fmt.Errorf("query constraint violations: %w", err)
}

var hasTable int
_ = db.QueryRow("SELECT COUNT(*) FROM information_schema.tables WHERE table_name='dolt_constraint_violations'").Scan(&hasTable)
// hasTable == 0 means no violation tracking / no violations

func violationsTableAvailable(db DBConn) bool {
    var n int
    _ = db.QueryRow("SELECT COUNT(*) FROM information_schema.tables WHERE table_name='dolt_constraint_violations'").Scan(&n)
    return n > 0
}

tables, err := constraintViolationTables(ctx, db)
if err != nil && strings.Contains(err.Error(), "query constraint violations") {
    if !violationsTableAvailable(db) {
        return nil // no violations possible
    }
    return err
}

When it happens

Trigger: SELECT `table` FROM dolt_constraint_violations WHERE num_violations > 0 fails — table missing (old Dolt version or no merge has run), server mode rejects the system-table query, or connection/transaction errors.

Common situations: Dolt version lacking the dolt_constraint_violations table; querying outside a session where merge metadata is loaded; server connection dropped.

Related errors

• failed to query cross-table duplicates: %w
• query cross-table duplicates: %w
• query constraint violations: %w
• scan constraint violation: %w
• iterate constraint violations: %w

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