What causes "'bd admin %s' is not yet supported in embedded mode" in gastownhall/beads?

Start/use server mode: initialize with `bd init --server` and run the admin command against the server

'bd admin %s' is not yet supported in embedded mode

Error message

'bd admin %s' is not yet supported in embedded mode

What it means

requireServerMode guards `bd admin` subcommands (e.g. reset) that are only implemented against a SQL server backend. When bd is running in embedded mode, the admin operation cannot be performed and this error names the subcommand. The check is intentionally placed inside RunE because ServerMode is only populated after main.go's PersistentPreRun completes.

Source

Thrown at cmd/bd/admin.go:17

package main

import (
	"fmt"

	"github.com/spf13/cobra"
)

// requireServerMode returns an error if bd is running in embedded mode.
// Used by admin subcommands to guard against embedded-mode execution.
// This must be called inside RunE (after store init), not in PersistentPreRunE,
// because !usesSQLServer() reads cmdCtx.ServerMode which is only populated
// after main.go's PersistentPreRun completes (cobra runs child PreRunE before
// parent PreRun, so the check fires too early if placed on adminCmd itself).
func requireServerMode(cmdName string) error {
	if !usesSQLServer() {
		return fmt.Errorf("'bd admin %s' is not yet supported in embedded mode", cmdName)
	}
	return nil
}

var adminCmd = &cobra.Command{
	Use:     "admin",
	GroupID: "advanced",
	Short:   "Administrative commands for database maintenance",
	Long: `Administrative commands for beads database maintenance.

These commands are for advanced users and should be used carefully:
  cleanup   Delete closed issues (issue lifecycle)
  compact   Compact old closed issues to save space (storage optimization)
  reset     Remove all beads data and configuration (full reset)

For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
automatically. Use these admin commands for targeted database operations.`,
}

View on GitHub (pinned to 71377f2769)

Solutions

Start/use server mode: initialize with `bd init --server` and run the admin command against the server
Skip the admin subcommand and use an embedded-mode equivalent (e.g. manual repair or bd doctor where gated)
Upgrade bd — embedded-mode support for admin subcommands is enabled one at a time (GH#3794)

Example fix

// before
bd admin reset
// error: 'bd admin reset' is not yet supported in embedded mode
// after
bd init --server && bd admin reset

Defensive patterns

Strategy: validation

Validate before calling

// check backend before invoking admin subcommands
if !usesSQLServer() {
    return errors.New("bd admin requires server mode; run bd init --server")
}

Try / catch

if err := bdAdminReset(ctx); err != nil {
    if strings.Contains(err.Error(), "not yet supported in embedded mode") {
        return initServerModeThenRetry()
    }
    return err
}

Prevention

Run admin commands only against server-mode repos
Gate admin automation on usesSQLServer() equivalent checks
Track GH#3794 for embedded-mode admin support rollouts

When it happens

Trigger: Running `bd admin <subcommand>` (e.g. `bd admin reset`) in a repository using an embedded (non-SQL-server) backend; usesSQLServer() returns false.

Common situations: Users on the default embedded Dolt setup attempting admin maintenance commands; scripts written against server-mode deployments run locally on embedded repos.

Related errors

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