{"record":{"id":"834c6fb7115cb375","repo":"gastownhall/beads","slug":"embeddeddolt-setting-branch-w","errorCode":null,"errorMessage":"embeddeddolt: setting branch: %w","messagePattern":"embeddeddolt: setting branch: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/embeddeddolt/store.go","lineNumber":338,"sourceCode":"\tdefer conn.Close()\n\n\tif s.database != \"\" {\n\t\tif !validIdentifier.MatchString(s.database) {\n\t\t\tmsg := fmt.Sprintf(\"embeddeddolt: invalid database name: %q\", s.database)\n\t\t\tif strings.ContainsRune(s.database, '-') {\n\t\t\t\tmsg += \"; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'\"\n\t\t\t}\n\t\t\treturn errors.New(msg)\n\t\t}\n\t\tif _, err := conn.ExecContext(ctx, \"CREATE DATABASE IF NOT EXISTS `\"+s.database+\"`\"); err != nil {\n\t\t\treturn fmt.Errorf(\"embeddeddolt: creating database: %w\", err)\n\t\t}\n\t\tif _, err := conn.ExecContext(ctx, \"USE `\"+s.database+\"`\"); err != nil {\n\t\t\treturn fmt.Errorf(\"embeddeddolt: switching to database: %w\", err)\n\t\t}\n\t\tif s.branch != \"\" {\n\t\t\tif _, err := conn.ExecContext(ctx, fmt.Sprintf(\"SET @@%s_head_ref = %s\", s.database, sqlStringLiteral(s.branch))); err != nil {\n\t\t\t\treturn fmt.Errorf(\"embeddeddolt: setting branch: %w\", err)\n\t\t\t}\n\t\t}\n\t}\n\n\t// Forward-drift guard: if this database's schema is AHEAD of the binary,\n\t// fail fast with a clear \"upgrade bd\" message before MigrateUp no-ops and a\n\t// later query dies on a dropped/renamed column. Embedded mode is the mode\n\t// the stale-binary incident (#4135/#4137) was observed in. The read-only\n\t// embedded open (OpenReadOnly) already guards this; the writable open did\n\t// not. Runs after the USE switch so the version read resolves against the\n\t// target database.\n\tif err := schema.CheckForwardDrift(ctx, conn); err != nil {\n\t\treturn err\n\t}\n\n\t// #4259: refuse to silently apply pending migrations to a remote-backed,\n\t// already-initialized database — independently migrating each clone forks the\n\t// schema. Embedded mode (the mode the original report was filed against) syncs","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/embeddeddolt/store.go#L320-L356","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the branch exists: check 'bd dolt branch' output or .beads metadata; fix typos in the configured branch name.","Fetch/pull remote branches ('bd dolt pull') so the branch exists locally.","Create the missing branch locally before pointing the store at it.","If the engine doesn't support head_ref, upgrade bd (matching engine version) or unset the branch override to use the default branch."],"exampleFix":"// before (.beads/metadata.json)\n{ \"dolt_branch\": \"feature/analytics\" } // branch not fetched locally\n\n// after\n$ bd dolt pull   # fetch branches\n// or remove the override:\n{ }","handlingStrategy":"validation","validationCode":"branch := meta.DoltBranch\nif branch != \"\" {\n    out, err := exec.Command(\"bd\", \"dolt\", \"branch\").Output()\n    if err != nil || !strings.Contains(string(out), branch) {\n        return fmt.Errorf(\"branch %q not present locally; run 'bd dolt pull' first\", branch)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := store.Init(ctx); err != nil && strings.Contains(err.Error(), \"setting branch\") {\n    if errors.Is(err, context.DeadlineExceeded) { /* retry */ }\n    // otherwise advise: fetch branch or unset dolt_branch in metadata\n    return err\n}","preventionTips":["Run 'bd dolt pull' after cloning or when teammates add branches before pointing at a branch","Validate dolt_branch in .beads/metadata.json matches an existing local branch","Keep bd upgraded so the engine supports @@*_head_ref","Don't hardcode feature branches in shared metadata"],"tags":["embedded-dolt","branch","configuration"],"backgroundTag":"dolt-branch-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}