unknown backend %q: the supported backend is "dolt" (default

Error message

unknown backend %q: the supported backend is "dolt" (default)

What it means

Generic branch of the backend check: any --backend value that is neither a known removed backend nor a supported/registered one gets this 'unknown backend' error. Dolt is the only supported default.

Source

Thrown at cmd/bd/init.go:542

				TLSServerName:   externalTLSServerName,
				TLSSkipVerify:   externalTLSSkipVerify,
				KeepAlivePeriod: externalKeepAlive,
			}
			if err := cfg.Validate(); err != nil {
				return fmt.Errorf("--proxied-server-external-*: %v", err)
			}
			externalConfig = &cfg
		}

		// Backend selection: Dolt is the only supported backend.
		if !configfile.IsSupportedBackend(backendFlag) {
			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)

View on GitHub (pinned to 71377f2769)

Solutions

Check the exact --backend value spelling (must be dolt for init)
Remove the --backend flag entirely to use the default
List registered backends via the configfile package or docs to see valid names

Example fix

// before
bd init --backend=postgress
// after
bd init --backend=dolt

Defensive patterns

Strategy: validation

Validate before calling

VALID_BACKENDS="dolt"
case ":$VALID_BACKENDS:" in
  *":$BACKEND:"*) ;;
  *) echo "unknown backend: $BACKEND"; exit 1 ;;
esac

Try / catch

if err := bdInit("--backend=" + backend); err != nil {
    if strings.Contains(err.Error(), "unknown backend") {
        // fix flag value or drop the flag
    }
}

Prevention

Only ever pass --backend=dolt for bd init
Copy flag values exactly; backend names are lowercase
Avoid building --backend values from unchecked variables

When it happens

Trigger: `bd init --backend=<typo>` such as --backend=postgress, --backend=doltdb, --backend=dolt; anything failing configfile.IsSupportedBackend and not matching postgres/mysql/sqlite.

Common situations: Typos in --backend values, case-sensitivity mistakes, copied flags from other tools (e.g. 'bolt', 'dolt'), empty or malformed values in scripts.

Related errors

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