gastownhall/beads · error · bootstrapPreparationError

uow: capture fresh database identity: %w

Error message

uow: capture fresh database identity: %w

What it means

In the same attempt that won the bare CREATE DATABASE, prepare calls schema.CaptureFreshBootstrapHealCapability to record the fresh-bootstrap ownership proof (endpoint, server UUID, database, initial HEAD). This error wraps a failure of that identity capture in a bootstrapPreparationError. It is thrown because the heal capability could not be captured, so the one-shot self-heal guard cannot be armed for this bootstrap.

Source

Thrown at internal/storage/uow/dolt_sql_provider.go:363

			}
		default:
			return nil, &bootstrapPreparationError{err: fmt.Errorf("uow: creating database: %w", err)}
		}
	}
	if err := ddl.UseDatabase(ctx, b.database); err != nil {
		return nil, &bootstrapPreparationError{err: fmt.Errorf("uow: switching to database: %w", err)}
	}
	if justCreated {
		// Capture authority only in the same attempt that won the exact bare
		// CREATE. A later retry may re-create a missing database for
		// availability, but it must never infer ownership of a replacement
		// incarnation from CREATE IF NOT EXISTS.
		var err error
		b.heal, err = schema.CaptureFreshBootstrapHealCapability(
			ctx, conn, b.provider.serverEndpoint, b.database,
		)
		if err != nil {
			return nil, &bootstrapPreparationError{err: fmt.Errorf("uow: capture fresh database identity: %w", err)}
		}
	}
	return b.heal, nil
}

func buildDSN(ep proxy.Endpoint, database, user, password, tlsConfigName string) string {
	return util.DoltServerDSN{
		Host:            ep.Host,
		Port:            ep.Port,
		User:            user,
		Password:        password,
		Database:        database,
		TLSConfigName:   tlsConfigName,
		ClientFoundRows: true,
	}.String()
}

func openDB(ctx context.Context, dsn string) (*sql.DB, error) {

View on GitHub (pinned to 71377f2769)

Solutions

1. Retry bd init on a stable connection — the CREATE will report already-exists, bootstrap continues, only the heal capability is skipped.
2. Ensure no concurrent process drops the database during init.
3. Check Dolt server version compatibility and that the server reports its UUID/HEAD correctly.
4. Inspect the wrapped driver error from the capture queries for the precise root cause.

// Before init: verify server exposes required metadata and is stable
conn, err := sql.Open("mysql", dsnWithoutDB)
if err != nil { return err }
if err := conn.PingContext(ctx); err != nil {
    return fmt.Errorf("server unreachable: %w", err)
}

func isBootstrapPreparationError(err error) (*uow.BootstrapPreparationError, bool) {
    var bpe *uow.BootstrapPreparationError
    if errors.As(err, &bpe) {
        return bpe, true
    }
    return nil, false
}

err := initProvider(ctx)
if err != nil {
    var bpe *uow.BootstrapPreparationError
    if errors.As(err, &bpe) && strings.Contains(bpe.Error(), "capture fresh database identity") {
        // heal capability not captured; init can be retried safely
        return retryWithBackoff(ctx)
    }
    return err
}

When it happens

Trigger: CaptureFreshBootstrapHealCapability's queries against the just-created database fail — e.g. the underlying connection errors, the server cannot report its UUID/HEAD, or the database disappears between CREATE and capture (concurrent drop).

Common situations: Unstable connection to a loaded shared Dolt server; embedded server restarted between CREATE and capture; concurrent clean-databases removing the fresh database; server version that does not expose the metadata the capture queries expect.

Related errors

• database %q not found on Dolt server at %s:%d
• clone from %s succeeded, but the database needs %d schema %s
• failed to migrate credential keys: %w
• failed to update encrypted password for peer %s: %w
• failed to initialize schema: %w

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