{"record":{"id":"934c6e3f29aa3235","repo":"gastownhall/beads","slug":"resolving-physical-root-s-w","errorCode":null,"errorMessage":"resolving physical root %s: %w","messagePattern":"resolving physical root (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/physical_root.go","lineNumber":271,"sourceCode":"\tpr := PhysicalRoots{BeadsDir: abs}\n\n\t// Side-effect-free config load: never trigger the legacy config.json\n\t// migration. Absent metadata.json is treated as cfg == nil.\n\tvar cfg *configfile.Config\n\tif _, statErr := os.Stat(configfile.ConfigPath(abs)); statErr == nil {\n\t\tloaded, loadErr := configfile.Load(abs)\n\t\tif loadErr != nil {\n\t\t\t// A present-but-broken metadata.json is authoritative: the open\n\t\t\t// path refuses to fall back, so gate planning refuses to guess.\n\t\t\treturn PhysicalRoots{}, fmt.Errorf(\"loading config for gate resolution: %w\", loadErr)\n\t\t}\n\t\tcfg = loaded\n\t}\n\n\taddRoot := func(root string) error {\n\t\trootAbs, aerr := filepath.Abs(root)\n\t\tif aerr != nil {\n\t\t\treturn fmt.Errorf(\"resolving physical root %s: %w\", root, aerr)\n\t\t}\n\t\tpr.Roots = append(pr.Roots, filepath.Clean(rootAbs))\n\t\treturn nil\n\t}\n\n\tswitch {\n\tcase cfg != nil && cfg.IsDoltProxiedServerMode():\n\t\tpr.Mode = \"proxied-server\"\n\t\troot, perr := ResolveProxiedServerRootPath(abs)\n\t\tif perr != nil {\n\t\t\treturn PhysicalRoots{}, fmt.Errorf(\"resolving proxied-server root: %w\", perr)\n\t\t}\n\t\tpr.Provenance = fmt.Sprintf(\"metadata.json dolt_mode=proxied-server; root %s via env/client-info/default\", root)\n\t\tif err := addRoot(root); err != nil {\n\t\t\treturn PhysicalRoots{}, err\n\t\t}\n\n\tcase IsSharedServerMode():","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/physical_root.go#L253-L289","documentation":"Inside ResolvePhysicalRoots, the addRoot helper wraps filepath.Abs(root) failures as \"resolving physical root %s: %w\". Each configured physical root (from metadata or env overrides) must be converted to an absolute, cleaned path before being added to PhysicalRoots.Roots; this error means one of those configured root strings could not be resolved — typically because the cwd is invalid or the root string is empty/malformed.","triggerScenarios":"A root entry from metadata.json or server-mode env overrides is an empty string (Abs falls back to getwd, which fails if cwd is gone) or a path exceeding OS limits; ResolvePhysicalRoots is invoked during startup or tests with such configuration.","commonSituations":"metadata.json contains an empty or whitespace physical-root value from a bad edit; bd launched from a deleted directory; extremely long Windows paths.","solutions":["Fix the offending root value in .beads/metadata.json (or the env override) — it must be a non-empty relative or absolute path.","Run bd from a valid existing directory, or pass absolute paths in configuration.","Shorten paths or enable Windows long-path support if path length is the cause.","Run bd doctor to validate metadata before starting the server."],"exampleFix":"// before\n{\"roots\": [\"\"]}   // empty root -> Abs(\"\") -> getwd error\n// after\n{\"roots\": [\"/home/u/proj\"]}","handlingStrategy":"validation","validationCode":"for _, root := range cfgRoots {\n    if strings.TrimSpace(root) == \"\" {\n        return fmt.Errorf(\"physical root entry is empty; fix metadata/env override\")\n    }\n}\nif _, err := os.Getwd(); err != nil {\n    return fmt.Errorf(\"cwd invalid; use absolute root paths\")\n}","typeGuard":"func rootResolvable(root string) bool {\n    if strings.TrimSpace(root) == \"\" { return false }\n    if filepath.IsAbs(root) { return true }\n    _, err := os.Getwd()\n    return err == nil\n}","tryCatchPattern":"roots, err := ResolvePhysicalRoots(beadsDir)\nif err != nil {\n    if strings.Contains(err.Error(), \"resolving physical root\") {\n        return fmt.Errorf(\"a configured root is unresolvable; check metadata.json roots and env overrides\")\n    }\n    return err\n}","preventionTips":["Store absolute paths for physical roots in metadata.json","Reject empty/whitespace root values when writing metadata","Run bd from a valid directory when roots are relative","Audit env overrides for the server mode before startup"],"tags":["filesystem","paths","configuration","metadata"],"backgroundTag":"path-resolution-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}