gastownhall/beads · error

--%s belonged to %s: %s; use --backend=dolt (the default)

Error message

--%s belonged to %s: %s; use --backend=dolt (the default)

What it means

Raised when a removed backend's legacy init flag (from removedBackendInitFlags) is still passed to bd init, e.g. old --sqlite or --postgres style flags. The message names the flag, its origin backend, the removal rationale, and points to --backend=dolt.

Source

Thrown at cmd/bd/init.go:554

			switch backendFlag {
			case configfile.BackendPostgres, configfile.BackendMySQL:
				return fmt.Errorf("storage backend %q is no longer supported: %s; the supported backend is \"dolt\" (default)", backendFlag, configfile.RemovedBackendRationale)
			case configfile.BackendSQLite:
				return fmt.Errorf("storage backend %q is no longer supported: %s; the supported backend is \"dolt\" (default)", backendFlag, configfile.RemovedSQLiteRationale)
			}
			return fmt.Errorf("unknown backend %q: the supported backend is \"dolt\" (default)", backendFlag)
		}
		// A registered extension backend passes IsSupportedBackend so its
		// existing workspaces can be opened, but init provisions Dolt only and
		// would otherwise create the workspace and persist backend: dolt. Reject
		// it here rather than silently creating the wrong workspace; downstream
		// registrants supply their own workspace-creation path.
		if backends.Registered(backendFlag) {
			return fmt.Errorf("backend %q cannot be created by bd init; it can only open an existing workspace (bd init provisions \"dolt\", the default)", backendFlag)
		}
		for _, legacyFlag := range removedBackendInitFlags {
			if cmd.Flags().Changed(legacyFlag.name) {
				return fmt.Errorf("--%s belonged to %s: %s; use --backend=dolt (the default)", legacyFlag.name, legacyFlag.origin, legacyFlag.rationale)
			}
		}
		// Validate --database format early, before any side effects.
		if database != "" {
			if err := dolt.ValidateDatabaseName(database); err != nil {
				return fmt.Errorf("invalid database name %q: %v", database, err)
			}
		}

		// Resolve non-interactive mode: flag > env var > terminal detection.
		// This must be computed before any interactive prompts.
		nonInteractive := isNonInteractiveInit(nonInteractiveFlag)

		// Validate --role flag value
		if roleFlag != "" {
			switch roleFlag {
			case "maintainer", "contributor":
				// valid

View on GitHub (pinned to 71377f2769)

Solutions

1. Remove the legacy flag from your command/alias
2. Replace it with --backend=dolt (or omit --backend, dolt is default)
3. Read the rationale in the message for the origin backend's removal
4. Search scripts/CI configs for the legacy flag name and clean it up

Example fix

// before
bd init --sqlite
// after
bd init   # dolt is the default backend

LEGACY_FLAGS=(--sqlite --postgres --mysql)
for f in "${LEGACY_FLAGS[@]}"; do
  case " $ARGS " in *" $f "*) echo "$f is removed; use --backend=dolt"; exit 1;; esac
done

if err := bdInit(args...); err != nil {
    if strings.Contains(err.Error(), "belonged to") {
        // strip the legacy flag and rerun with --backend=dolt
    }
}

When it happens

Trigger: Running `bd init` with a legacy removed-backend flag listed in removedBackendInitFlags that cmd.Flags().Changed() reports as set.

Common situations: Old shell aliases or wrapper scripts from pre-Dolt beads versions; muscle-memory flags like --sqlite; users following outdated blog posts or docs.

Related errors

• storage backend %q is no longer supported: %s; the supported
• --server and --proxied-server are mutually exclusive
• --proxied-server cannot be combined with --shared-server, --
• --team-server requires --proxied-server
• --proxied-server-config-path requires --proxied-server

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