{"record":{"id":"330dfee397769da1","repo":"gastownhall/beads","slug":"storage-errunsupported","errorCode":"storage.ErrUnsupported","errorMessage":"%w: bd serve requires a Dolt SQL server; this workspace uses embedded Dolt","messagePattern":"%w: bd serve requires a Dolt SQL server; this workspace uses embedded Dolt","errorType":"exception","errorClass":"storage.ErrUnsupported","httpStatus":null,"severity":"error","filePath":"cmd/bd/serve.go","lineNumber":619,"sourceCode":"// `readonly` is also a config key, and PersistentPreRunE has already folded\n// both into readonlyMode by the time any RunE runs.\nfunc errServeReadonly() error {\n\treturn errors.New(\"bd serve is unavailable under strict readonly (--readonly, or readonly in config): \" +\n\t\t\"every server it binds publishes the issue-claim operation, and refusing to start is the only honest \" +\n\t\t\"answer — a server that advertised a claim it could never land would be worse than no server\")\n}\n\n// errServeEmbedded is the PERMANENT refusal. The message says what the\n// workspace is and what serve needs, and promises nothing further: the reason\n// is the embedded backend's commit protocol (see serveDatabaseSource), which no\n// amount of provider or role plumbing changes.\n//\n// The mode belongs in the message, not in ErrUnsupported.Backend: that field is\n// documented as a BACKEND name and is the embryo of the pluggable-backend error\n// taxonomy, so putting a topology string in it would hand every downstream\n// errors.As a mixed backend/mode vocabulary.\nfunc errServeEmbedded() error {\n\treturn fmt.Errorf(\"%w: bd serve requires a Dolt SQL server; this workspace uses embedded Dolt\",\n\t\t&storage.ErrUnsupported{Op: \"serve\", Backend: \"embedded-dolt\"})\n}\n\n// serveRoleSource is the surface serveIssueRoles reaches on the store, spelled\n// out rather than taken as a whole storage.DoltStorage.\n//\n// THE POINT IS THE TEST STUBS. A stub that stands in for a store has to satisfy\n// whatever this function asks for, and the only affordable way to satisfy a\n// hundred-method interface is to embed it and leave it nil — which answers every\n// accessor the stub forgot with a promoted method on a nil interface. That is a\n// segfault inside the loop below rather than a compile error, and it has landed\n// twice: once on GraphCounter in serve_source_test.go, and once on the same role\n// in serve_store_identity_test.go, where no local -run pattern named the test\n// and only a full-package CI shard found it.\n//\n// Named narrowly, a stub can DECLARE this set and assert it, so the next role\n// added to the loop below is a build failure in the file that has to grow a\n// method — with the method's name in the error.","sourceCodeStart":601,"sourceCodeEnd":637,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/serve.go#L601-L637","documentation":"errServeEmbedded returns a storage.ErrUnsupported (Op: \"serve\", Backend: \"embedded-dolt\") wrapped with an explanation: bd serve only works against a Dolt SQL server, not the embedded Dolt topology. The mode is kept in the message, not in ErrUnsupported.Backend, so the error taxonomy's Backend field stays a pure backend vocabulary for errors.As matching.","triggerScenarios":"Running `bd serve` in a workspace whose metadata.json/config resolves to embedded Dolt mode (isEmbeddedMode() true), e.g. embedded mode enabled per GH#3794 gating.","commonSituations":"Developer workspace using embedded Dolt locally tries to expose the HTTP API via bd serve; CI environments defaulting to embedded mode; mixed setups after switching backends between server and embedded.","solutions":["Provision and connect to a real Dolt SQL server, then configure the workspace backend to it.","Use the Dolt-backed server mode (dolthub/driver via a dolt sql-server) before running bd serve.","Handle this error in tooling with errors.As(*storage.ErrUnsupported) and route embedded-mode users to a different command.","Do not attempt to \"fix\" by editing ErrUnsupported.Backend — the message carries the mode by design."],"exampleFix":"// handle in caller\nvar ue *storage.ErrUnsupported\nif errors.As(err, &ue) && ue.Op == \"serve\" {\n    fmt.Fprintln(os.Stderr, \"bd serve unavailable in embedded mode; start a Dolt SQL server\")\n}","handlingStrategy":"type-guard","validationCode":"// before bd serve, check mode\nif isEmbeddedMode() {\n    return errors.New(\"bd serve requires a Dolt SQL server; embedded mode not supported\")\n}","typeGuard":"var ue *storage.ErrUnsupported\nif errors.As(err, &ue) && ue.Op == \"serve\" && ue.Backend == \"embedded-dolt\" {\n    // embedded topology: bd serve unavailable\n}","tryCatchPattern":"if err := runServe(...); err != nil {\n    var ue *storage.ErrUnsupported\n    if errors.As(err, &ue) {\n        // route to server-mode setup instructions\n    }\n}","preventionTips":["Only run bd serve against workspaces configured for a Dolt SQL server.","Detect embedded mode before invoking serve and warn users.","Keep mode checks in tooling via errors.As, not by parsing Backend as a mode (by design).","Provision a dolt sql-server for shared/serve use cases."],"tags":["serve","embedded-dolt","storage","unsupported-operation"],"backgroundTag":"embedded-mode-unsupported","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}