gastownhall/beads · error

embeddeddolt: setting branch: %w

Error message

embeddeddolt: setting branch: %w

What it means

Wraps the error from 'SET @@<db>_head_ref = <branch>' in initSchema, executed when s.branch is configured. It means the engine accepted database creation/selection but refused to set the Dolt branch head reference — the branch name may not exist, the session variable may be unknown to this engine version, or the connection/context failed. The store cannot operate on the requested branch, so initialization aborts.

Source

Thrown at internal/storage/embeddeddolt/store.go:338

	defer conn.Close()

	if s.database != "" {
		if !validIdentifier.MatchString(s.database) {
			msg := fmt.Sprintf("embeddeddolt: invalid database name: %q", s.database)
			if strings.ContainsRune(s.database, '-') {
				msg += "; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'"
			}
			return errors.New(msg)
		}
		if _, err := conn.ExecContext(ctx, "CREATE DATABASE IF NOT EXISTS `"+s.database+"`"); err != nil {
			return fmt.Errorf("embeddeddolt: creating database: %w", err)
		}
		if _, err := conn.ExecContext(ctx, "USE `"+s.database+"`"); err != nil {
			return fmt.Errorf("embeddeddolt: switching to database: %w", err)
		}
		if s.branch != "" {
			if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET @@%s_head_ref = %s", s.database, sqlStringLiteral(s.branch))); err != nil {
				return fmt.Errorf("embeddeddolt: setting branch: %w", err)
			}
		}
	}

	// Forward-drift guard: if this database's schema is AHEAD of the binary,
	// fail fast with a clear "upgrade bd" message before MigrateUp no-ops and a
	// later query dies on a dropped/renamed column. Embedded mode is the mode
	// the stale-binary incident (#4135/#4137) was observed in. The read-only
	// embedded open (OpenReadOnly) already guards this; the writable open did
	// not. Runs after the USE switch so the version read resolves against the
	// target database.
	if err := schema.CheckForwardDrift(ctx, conn); err != nil {
		return err
	}

	// #4259: refuse to silently apply pending migrations to a remote-backed,
	// already-initialized database — independently migrating each clone forks the
	// schema. Embedded mode (the mode the original report was filed against) syncs

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the branch exists: check 'bd dolt branch' output or .beads metadata; fix typos in the configured branch name.
2. Fetch/pull remote branches ('bd dolt pull') so the branch exists locally.
3. Create the missing branch locally before pointing the store at it.
4. If the engine doesn't support head_ref, upgrade bd (matching engine version) or unset the branch override to use the default branch.

Example fix

// before (.beads/metadata.json)
{ "dolt_branch": "feature/analytics" } // branch not fetched locally

// after
$ bd dolt pull   # fetch branches
// or remove the override:
{ }

branch := meta.DoltBranch
if branch != "" {
    out, err := exec.Command("bd", "dolt", "branch").Output()
    if err != nil || !strings.Contains(string(out), branch) {
        return fmt.Errorf("branch %q not present locally; run 'bd dolt pull' first", branch)
    }
}

if err := store.Init(ctx); err != nil && strings.Contains(err.Error(), "setting branch") {
    if errors.Is(err, context.DeadlineExceeded) { /* retry */ }
    // otherwise advise: fetch branch or unset dolt_branch in metadata
    return err
}

When it happens

Trigger: newStore -> initSchema with s.branch != "" where: (1) the configured branch does not exist in the embedded database (never created, or remote branch not fetched); (2) the embedded Dolt engine version doesn't support @@<db>_head_ref; (3) sqlStringLiteral quoting or ctx cancellation causes the SET to fail.

Common situations: dolt_branch set in .beads/metadata.json to a branch that exists on the remote but hasn't been fetched; typos in the branch name; bd built against a newer/older Dolt engine than the data directory was created with; teammate created a feature branch that your local clone lacks.

Related errors

• invalid database name: %q; hyphens are not allowed in embedd
• embeddeddolt: invalid database name: %q; hyphens are not all
• embeddeddolt: active database directory is empty
• multiple .doltcfg directories detected
• dolt directory is required

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