{"record":{"id":"07ade33263fa3b03","repo":"gastownhall/beads","slug":"load-s-w","errorCode":null,"errorMessage":"load %s: %w","messagePattern":"load (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/bd/serve.go","lineNumber":561,"sourceCode":"// be handed to the Dolt provider and fail with a misleading Dolt error — or\n// connect to a defaulted host and serve the wrong database.\n//\n// EMBEDDED DOLT IS PERMANENT, and this is the only place that refusal lives.\n// Its commit protocol runs outside the SQL transaction on a separate\n// connection, so the per-request atomicity this server's contract states would\n// be a lie there. That is a property of the backend rather than of what has\n// been built so far, which is also why no unit-of-work provider for it exists\n// or will. Nothing downstream will catch a bypass: internal/httpapi cannot see\n// the backend behind a role, and every store publishes every role accessor\n// whatever it is. TestServeNamesOneDatabaseSourcePerServerItBuilds pins that\n// the roles are only ever reached through here.\nfunc serveDatabaseSource(beadsDir string) (serveDatabase, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil {\n\t\t// Never classify past an unreadable metadata.json. The classification's\n\t\t// default is the embedded refusal, so falling back would refuse a\n\t\t// workspace whose real backend nobody managed to read.\n\t\treturn serveDatabase{}, fmt.Errorf(\"load %s: %w\", configfile.ConfigPath(beadsDir), err)\n\t}\n\tif backend := normalizeLoadedConfig(cfg).GetBackend(); backends.Registered(backend) {\n\t\treturn serveDatabase{source: serveSourceStore, backend: backend}, nil\n\t}\n\tif isEmbeddedMode() {\n\t\treturn serveDatabase{}, errServeEmbedded()\n\t}\n\treturn serveDatabase{source: serveSourceProvider}, nil\n}\n\n// errServeReadonly refuses `bd --readonly serve`.\n//\n// AHEAD OF THE WORKSPACE, deliberately: every server this command builds\n// publishes the same operation set, claim included, so the answer cannot depend\n// on which database source the workspace resolves to. Putting it here is also\n// what makes it one answer rather than two — the two sources degraded\n// differently, and both silently.\n//","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/serve.go#L543-L579","documentation":"serveDatabaseSource refuses to continue when metadata.json (via configfile.Load) cannot be read or parsed. Per the comment, this is a hard error: the classification's default is an embedded refusal, so falling back would silently refuse a workspace whose backend nobody could read. The error names the actual config path plus the underlying cause.","triggerScenarios":"`bd serve` in a workspace where .beads/metadata.json is corrupt, malformed JSON, unreadable, or locked; ConfigPath(beadsDir) points at a file the process cannot read.","commonSituations":"Hand-edited metadata.json with invalid JSON; interrupted write left a truncated metadata.json; permission issues after cloning a repo as another user; concurrent writes corrupting the file.","solutions":["Inspect the file named in the error (the metadata.json path) for valid JSON and fix it.","Restore metadata.json from git or re-run `bd init`/backend setup to regenerate it.","Fix file permissions for the serving user.","Inspect the wrapped err via errors.Unwrap/errors.Is for the exact I/O or parse cause."],"exampleFix":"// after failure, inspect and repair:\npython3 -m json.tool .beads/metadata.json  # show parse error\ngit checkout -- .beads/metadata.json        # or fix manually, then retry bd serve","handlingStrategy":"try-catch","validationCode":"if _, err := os.Stat(configfile.ConfigPath(beadsDir)); err != nil {\n    // metadata.json missing entirely — run bd init or backend setup\n}","typeGuard":null,"tryCatchPattern":"db, err := serveDatabaseSource(beadsDir)\nif err != nil {\n    // validate/repair the metadata.json named in the error; never assume embedded fallback\n    return err\n}","preventionTips":["Never hand-edit metadata.json without validating JSON afterwards.","Commit a valid metadata.json so clones start from a good state.","Avoid killing bd mid-write; let writes complete.","If the file is corrupt, restore from git or regenerate via bd init."],"tags":["serve","configuration","metadata","storage"],"backgroundTag":"corrupt-config-file","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}