gastownhall/beads · critical

storage backend %q is no longer supported: %s

Error message

storage backend %q is no longer supported: %s

What it means

RemovedBackendError is bd's fail-closed error when metadata.json selects a storage backend whose direct support was removed (e.g. sqlite). It guarantees the configured database was NOT opened or modified, and instructs exporting with an older bd version before reinitializing with Dolt.

Source

Thrown at internal/configfile/backend_messages.go:44

// removedBackendRationale picks the rationale clause for a removed backend.
func removedBackendRationale(backend string) string {
	if backend == BackendSQLite {
		return RemovedSQLiteRationale
	}
	return RemovedBackendRationale
}

// RemovedBackendDetail returns the shared body of every removed-backend error:
// the rationale, the untouched-data guarantee, and the migration path. Callers
// prepend a site-specific lead-in; RemovedBackendError carries the standard one.
func RemovedBackendDetail(backend string) string {
	return fmt.Sprintf("%s; the configured %s database was not opened or modified; export it with a bd version that supports %s, then follow bd help init-safety to reinitialize with Dolt and import the exported data", removedBackendRationale(backend), backend, backend)
}

// RemovedBackendError is the standard fail-closed error for metadata that
// selects a backend whose direct support was removed.
func RemovedBackendError(backend string) error {
	return fmt.Errorf("storage backend %q is no longer supported: %s", backend, RemovedBackendDetail(backend))
}

// UnknownBackendError is the standard fail-closed error for metadata that
// names a backend this build does not recognize.
func UnknownBackendError(backend string) error {
	return fmt.Errorf("storage backend %q in metadata.json is not recognized or supported; %s; the supported backend is %q; fix or restore metadata.json and retry", backend, BackendNotOpenedGuarantee, BackendDolt)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Install a bd version that still supports the backend and run `bd export` to dump the issues
2. Follow the `bd help init-safety` runbook to reinitialize the workspace with Dolt
3. Import the exported data into the fresh Dolt-backed database
4. Update metadata.json only via the supported reinit flow, never by hand-editing

Example fix

// before (metadata.json)
{"backend":"sqlite"}
// after
bd export -f issues.jsonl && bd init  # then bd import issues.jsonl with Dolt backend

meta, _ := os.ReadFile(filepath.Join(".beads", "metadata.json"))
var m struct{ Backend string `json:"backend"` }
if json.Unmarshal(meta, &m) == nil && m.Backend != "" && m.Backend != "dolt" {
    // stop: unsupported backend — use an older bd to export first
}

func isRemovedBackend(b string) bool {
    switch b { case "sqlite", "sqlite3": return true; default: return false }
}

if err := bd.Run(...); err != nil {
    var rbe *bd.RemovedBackendError
    if errors.As(err, &rbe) {
        fmt.Fprintln(os.Stderr, "backend removed: export with older bd, then reinit per bd help init-safety")
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: Running any bd command in a workspace whose .beads/metadata.json names a removed backend; RemovedBackendError is returned during backend resolution at startup.

Common situations: Upgrading bd after a backend was deprecated/removed; cloning a repo created with an old bd version that used sqlite.

Related errors

• configured storage backend %q is no longer supported and can
• not using Dolt backend (configured backend %q)
• storage backend has no underlying database
• read labels for %s: %w
• copy label %q for %s: %w

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