refusing to auto-commit %d dirty internal config key(s) befo

Error message

refusing to auto-commit %d dirty internal config key(s) before pull: %s; only user %s* keys auto-commit before a pull (GH#2455) — commit or revert these explicitly with `bd dolt commit` first

What it means

A guard error: before a pull, the store refuses to auto-commit because the working set contains dirty INTERNAL config keys (keys under the dolt-internal prefix, not user keys). Only user %s* keys are auto-committed before pull (GH#2455), to avoid sweeping up stale internal changes.

Source

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

		return fmt.Errorf("inspect dirty config before pull: %w", err)
	}
	defer rows.Close()

	var unsafe []string
	for rows.Next() {
		var key sql.NullString
		if err := rows.Scan(&key); err != nil {
			return fmt.Errorf("scan dirty config key: %w", err)
		}
		if key.Valid && !strings.HasPrefix(key.String, kvkeys.Prefix) {
			unsafe = append(unsafe, key.String)
		}
	}
	if err := rows.Err(); err != nil {
		return fmt.Errorf("iterate dirty config diff: %w", err)
	}
	if len(unsafe) > 0 {
		return fmt.Errorf("refusing to auto-commit %d dirty internal config key(s) before pull: %s; "+
			"only user %s* keys auto-commit before a pull (GH#2455) — commit or revert "+
			"these explicitly with `bd dolt commit` first", len(unsafe), strings.Join(unsafe, ", "), kvkeys.Prefix)
	}
	return nil
}

// CommitWithConfig creates a Dolt commit that includes the config table.
// Use this instead of Commit when the caller intentionally modified config
// (e.g., CommitPending after 'bd config set', 'bd init', or 'bd rename-prefix').
// GH#2455: Commit() excludes config to prevent sweeping up stale changes.
func (s *DoltStore) CommitWithConfig(ctx context.Context, message string) error {
	return s.withCircuitWrite(ctx, func(ctx context.Context) error {
		conn, err := s.db.Conn(ctx)
		if err != nil {
			return fmt.Errorf("failed to acquire connection: %w", err)
		}
		defer conn.Close()

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd dolt commit` (or revert the internal keys) explicitly as the message instructs, then re-run the pull.
Use `bd dolt status` to list the offending internal keys.
Revert unwanted internal changes instead of committing them if they are stale.

Example fix

// before
bd sync  // fails: refusing to auto-commit 1 dirty internal config key(s)
// after
bd dolt commit -m "commit internal config"
bd sync

Defensive patterns

Strategy: validation

Validate before calling

// check for dirty internal keys before pull
out, _ := exec.Command("bd", "dolt", "status", "--json").Output()
if strings.Contains(string(out), internalConfigPrefix) {
    return errors.New("dirty internal config keys; run `bd dolt commit` first")
}

Try / catch

if strings.Contains(err.Error(), "refusing to auto-commit") {
    fmt.Fprintln(os.Stderr, "run `bd dolt commit` (or revert) then retry the pull")
    return err
}

Prevention

Always complete or revert `bd config set` / `bd rename-prefix` operations before syncing.
Avoid editing internal config keys via raw SQL.
Run `bd dolt status` before pull to catch dirty keys early.
Avoid running parallel bd commands that mutate config concurrently.

When it happens

Trigger: Calling pull / sync (which pre-commits via this path) while internal config keys (e.g. set by `bd config set` on internal keys, init, or rename-prefix) are modified and uncommitted.

Common situations: A crashed or interrupted `bd config set`/`bd rename-prefix` left internal config rows dirty; parallel bd processes edited internal keys; manual SQL edits to the config table.

Related errors

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