gastownhall/beads · error

not using Dolt backend (configured backend %q)

Error message

not using Dolt backend (configured backend %q)

What it means

requireDoltBackend enforces that the configured storage backend is Dolt. After validateConfiguredBackend passes, if cfg is non-nil and cfg.GetBackend() != BackendDolt, it returns this error embedding the actual backend name in %q. Callers that only support Dolt (e.g. loadDoltBackendConfig) use it to fail fast with a clear mismatch message.

Source

Thrown at cmd/bd/backend_support.go:41

		return configfile.UnknownBackendError(cfg.Backend)
	}
}

// registeredBackendWorkspaceIsBeadsDir reports whether metadata selects a
// backend that has no separately discoverable local database.
func registeredBackendWorkspaceIsBeadsDir(cfg *configfile.Config) bool {
	if cfg == nil {
		return false
	}
	return backends.WorkspaceIsBeadsDir(cfg.GetBackend())
}

func requireDoltBackend(cfg *configfile.Config) error {
	if err := validateConfiguredBackend(cfg); err != nil {
		return err
	}
	if cfg != nil && cfg.GetBackend() != configfile.BackendDolt {
		return fmt.Errorf("not using Dolt backend (configured backend %q)", cfg.GetBackend())
	}
	return nil
}

// normalizeLoadedConfig substitutes the default config for an absent
// metadata.json (cfg == nil) so mode inference still runs: a remote host
// supplied via BEADS_DOLT_SERVER_HOST or config.yaml dolt.host (GH#3545)
// must select server mode even when no metadata.json exists — otherwise
// the CLI silently opens the embedded store against a remote-host
// configuration.
func normalizeLoadedConfig(cfg *configfile.Config) *configfile.Config {
	if cfg == nil {
		return configfile.DefaultConfig()
	}
	return cfg
}

func loadDoltBackendConfig(beadsDir string) (*configfile.Config, error) {

View on GitHub (pinned to 71377f2769)

Solutions

1. Update the backend setting to dolt (via bd's config/metadata mechanism, e.g. re-running the documented init/migrate flow).
2. Read the %q in the message — it names the current backend so you can find where it is set.
3. If you must keep the other backend, use the non-Dolt code path/command instead of the Dolt-required one.
4. Migrate existing data per the backend-migration docs before switching, then verify with the same command that previously failed.

Example fix

// before
# .beads config
backend = "sqlite"

// after
backend = "dolt"   # then rerun the command

cfg, err := loadConfig()
if err != nil { return err }
if cfg.GetBackend() != "dolt" {
	return fmt.Errorf("this command requires the dolt backend; got %q", cfg.GetBackend())
}

func isDoltConfig(cfg *configfile.Config) bool {
	return cfg != nil && cfg.GetBackend() == configfile.BackendDolt
}

if err := requireDoltBackend(cfg); err != nil {
	var beErr = err // message embeds current backend via %q
	log.Printf("backend mismatch: %v — migrate or switch backend", beErr)
	return beErr
}

When it happens

Trigger: Calling requireDoltBackend (directly or via loadDoltBackendConfig) with a config whose metadata/config file selects a backend other than "dolt" (e.g. "sqlite", "jsonl", "redis"), or running tests that exercise a non-Dolt backend configuration.

Common situations: A .beads/metadata.json or config file written when the project used a legacy/alternate backend; manually switching backends without migrating; copy-pasting config from a non-Dolt setup; environments where the team standardized on Dolt but one checkout still points elsewhere.

Related errors

• storage backend %q is not registered
• configured storage backend %q is no longer supported and can
• configured storage backend %q in metadata.json is not recogn
• configured storage backend %q cannot be opened as Dolt
• uow: external TLS: %w

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