gastownhall/beads · error

dolt.mode must be "server" or "embedded", got %q

Error message

dolt.mode must be "server" or "embedded", got %q

What it means

validateYamlConfigValue validates a single key/value pair before bd writes it to a YAML config file. For the dolt.mode key the value must be exactly "server" or "embedded" (case-insensitive); any other string is rejected with this error so bd never persists an invalid Dolt runtime mode.

Source

Thrown at internal/config/yaml_config.go:901

			return fmt.Errorf("hierarchy.max-depth must be a positive integer, got %q", value)
		}
		if depth < 1 {
			return fmt.Errorf("hierarchy.max-depth must be at least 1, got %d", depth)
		}
	case "dolt.shared-server":
		lower := strings.ToLower(value)
		if lower != "true" && lower != "false" {
			return fmt.Errorf("dolt.shared-server must be \"true\" or \"false\", got %q", value)
		}
	case "dolt.debug":
		lower := strings.ToLower(value)
		if lower != "true" && lower != "false" {
			return fmt.Errorf("dolt.debug must be \"true\" or \"false\", got %q", value)
		}
	case "dolt.mode":
		lower := strings.ToLower(value)
		if lower != "server" && lower != "embedded" {
			return fmt.Errorf("dolt.mode must be \"server\" or \"embedded\", got %q", value)
		}
	case "prime.max-memories":
		n, err := strconv.Atoi(value)
		if err != nil {
			return fmt.Errorf("prime.max-memories must be a non-negative integer (0 = unlimited), got %q", value)
		}
		if n < 0 {
			return fmt.Errorf("prime.max-memories must be a non-negative integer (0 = unlimited), got %q", value)
		}
	case "prime.max-memory-chars":
		n, err := strconv.Atoi(value)
		if err != nil {
			return fmt.Errorf("prime.max-memory-chars must be a non-negative integer (0 = unlimited), got %q", value)
		}
		if n < 0 {
			return fmt.Errorf("prime.max-memory-chars must be a non-negative integer (0 = unlimited), got %q", value)
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Set dolt.mode to exactly "server" or "embedded", e.g. `bd config set dolt.mode embedded`
2. Check the current value with `bd config get dolt.mode` and edit the YAML config file manually if a bad value was persisted
3. If value came from a script or env, trim whitespace and lowercase it before passing

Example fix

// before
SetYamlConfig("dolt.mode", "local")
// after
SetYamlConfig("dolt.mode", "embedded")

v := strings.ToLower(strings.TrimSpace(value))
if v != "server" && v != "embedded" {
    return fmt.Errorf("dolt.mode must be server or embedded, got %q", value)
}

if err := bd.SetYamlConfig("dolt.mode", v); err != nil {
    var verr *bd.ValidationError
    if errors.As(err, &verr) { /* show allowed values: server, embedded */ }
}

When it happens

Trigger: Calling SetYamlConfig, SetYamlConfigInDir, or SetUserYamlConfig with key "dolt.mode" and a value other than server/embedded (e.g. `bd config set dolt.mode local`), or test code invoking validateYamlConfigValue directly.

Common situations: Typo in the mode name, abbreviations like "local" or "standalone", leftover value from a doc or old version, or whitespace-bearing shell input.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• ErrPrefixMismatch
• invalid key %q: expected storage-class.<issue-type> (e.g. st

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