database name %q contains hyphens which are invalid in embed

Error message

database name %q contains hyphens which are invalid in embedded mode; use underscores instead (e.g. %q)

What it means

bd init rejects a --database name containing hyphens when running in embedded mode (no SQL server). Hyphens are invalid identifiers for the embedded Dolt database, so bd fails fast with a suggested sanitized name. This check must run after server mode detection so server-mode names are not wrongly rejected.

Source

Thrown at cmd/bd/init.go:726

		// Explicit connection flags outrank stale BEADS_DOLT_SERVER_* values
		// (GH#5177). This must run AFTER every source of server mode has been
		// consulted above: --server, BEADS_DOLT_SERVER_MODE, --shared-server,
		// workspace inheritance, and config.yaml dolt.mode. In embedded mode
		// the flags are still recorded in metadata.json, but promoting them
		// into the environment would trip init's own remote-host guard below.
		if initServerMode {
			restoreServerConnEnv, err := promoteExplicitServerConnFlags(cmd)
			if err != nil {
				return err
			}
			defer restoreServerConnEnv()
		}

		// Reject hyphens in --database for embedded mode. Must run AFTER
		// serverMode is set above — otherwise !usesSQLServer() always returns
		// true and incorrectly rejects server-mode names (GH#3231).
		if database != "" && strings.ContainsRune(database, '-') && !usesSQLServer() {
			return fmt.Errorf("database name %q contains hyphens which are invalid in embedded mode; use underscores instead (e.g. %q)",
				database, sanitizeDBName(database))
		}

		// Hard fail: if a remote dolt.host is configured, server mode MUST
		// be active — embedded mode has no host. dolt.port alone is ambient
		// plumbing (e.g. test harnesses) and is not treated as server intent.
		if !initServerMode {
			configHost := config.GetYamlConfig("dolt.host")
			envHost := os.Getenv("BEADS_DOLT_SERVER_HOST")
			configPort := config.GetYamlConfig("dolt.port")
			envPort := os.Getenv("BEADS_DOLT_SERVER_PORT")

			if conflict := detectInitRemoteHostConflict(configHost, envHost, configPort, envPort); conflict != nil {
				detail := fmt.Sprintf("dolt.host (%s) is", conflict.host)
				if conflict.includesPort {
					detail = fmt.Sprintf("dolt.host (%s) and dolt.port are", conflict.host)
				}
				return fmt.Errorf("%s set via %s but server mode is not enabled.\n"+

View on GitHub (pinned to 71377f2769)

Solutions

Replace hyphens with underscores: bd init --database my_db
Use the suggested name shown in the error message (sanitizeDBName output)
Switch to server mode if hyphenated names are required: dolt.mode: server in config or pass --server to bd init

Example fix

// before
bd init --database beads-proj-alpha
// after
bd init --database beads_proj_alpha

Defensive patterns

Strategy: validation

Validate before calling

if [[ "$DB_NAME" == *-* ]]; then echo "Use underscores instead of hyphens: ${DB_NAME//-/_}"; fi

Prevention

Derive database names from branch/slug names with tr '-' '_' before passing to bd init
Keep a project convention: always lowercase, underscore-separated database names
Enable server mode explicitly in config if you need hyphenated names

When it happens

Trigger: Running `bd init --database my-db` (or config dolt.database with hyphens) while the workspace resolves to embedded mode, i.e. !usesSQLServer() (no --server, no dolt.mode: server, no remote dolt.host).

Common situations: Users copying database names from branch names or project slugs like 'proj-alpha'; CI scripts templating names from git branch names which contain hyphens.

Related errors

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