{"record":{"id":"8cf1f8e85069761f","repo":"gastownhall/beads","slug":"writing-dolt-compatibility-marker-s-w","errorCode":null,"errorMessage":"writing dolt compatibility marker %s: %w","messagePattern":"writing dolt compatibility marker (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1921,"sourceCode":"\t\treturn errors.New(\"dolt directory is required\")\n\t}\n\tdotDolt := filepath.Join(doltDir, \".dolt\")\n\tif info, err := os.Stat(dotDolt); err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\"checking dolt metadata directory %s: %w\", dotDolt, err)\n\t} else if !info.IsDir() {\n\t\treturn fmt.Errorf(\"dolt metadata path %s is not a directory\", dotDolt)\n\t}\n\tmarkerPath := filepath.Join(doltDir, bdDoltMarker)\n\tif _, err := os.Stat(markerPath); err == nil {\n\t\treturn nil\n\t} else if !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"checking dolt compatibility marker %s: %w\", markerPath, err)\n\t}\n\tif err := os.WriteFile(markerPath, []byte(\"ok\\n\"), 0600); err != nil {\n\t\treturn fmt.Errorf(\"writing dolt compatibility marker %s: %w\", markerPath, err)\n\t}\n\treturn nil\n}\n\n// ensureDoltInit initializes a dolt database directory if .dolt/ doesn't exist.\n// If .dolt/ exists, seeds the .bd-dolt-ok marker for existing working databases.\n// See GH#2137 for background on pre-0.56 database compatibility.\nfunc ensureDoltInit(doltDir string) error {\n\tif err := os.MkdirAll(doltDir, config.BeadsDirPerm); err != nil {\n\t\treturn fmt.Errorf(\"creating dolt directory: %w\", err)\n\t}\n\n\tdotDolt := filepath.Join(doltDir, \".dolt\")\n\n\tif _, err := os.Stat(dotDolt); err == nil {\n\t\t// .dolt/ exists — seed the marker if missing.\n\t\t// This is the non-destructive path: we just mark existing databases\n\t\t// as known. The destructive recovery path (RecoverPreV56DoltDir) is","sourceCodeStart":1903,"sourceCodeEnd":1939,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1903-L1939","documentation":"Returned by MarkDoltDirCompatible when os.WriteFile fails to create the .bd-dolt-ok compatibility marker inside the dolt database directory. The marker records that the repository was created/acknowledged by bd 0.56+ (server-mode compatible); without it, bd may later treat the database as a pre-0.56 legacy database. The wrapped error comes from the filesystem (permissions, full disk, etc.).","triggerScenarios":"Calling MarkDoltDirCompatible (directly or via ensureDoltInit after a successful 'dolt init') on a doltDir whose parent directory is not writable by the current user, where a file named .bd-dolt-ok already exists as a read-only/non-writable regular file, or on a full read-only filesystem.","commonSituations":"Running bd under a different user than the one that created .beads (e.g. sudo vs. local user); .beads mounted read-only or on a full disk; an admin manually created a non-writable .bd-dolt-ok file; container volume with wrong ownership.","solutions":["Fix permissions on the dolt directory (and any existing marker file) so the current user can write, e.g. chown -R $(whoami) .beads","If a non-writable .bd-dolt-ok file exists, remove it: rm .beads/.bd-dolt-ok (it will be recreated with mode 0600)","Check that the filesystem containing doltDir is not full or mounted read-only (df -h, mount | grep ro) and free space or remount","Re-run the bd command; MarkDoltDirCompatible is retried defensively on future runs"],"exampleFix":"// before (shell, database owned by root)\n$ bd ready\n# error: writing dolt compatibility marker /path/.beads/.bd-dolt-ok: open ...: permission denied\n// after\n$ sudo chown -R $(whoami) /path/.beads\n$ bd ready","handlingStrategy":"validation","validationCode":"markerPath := filepath.Join(doltDir, \".bd-dolt-ok\")\nif info, err := os.Stat(doltDir); err != nil || !info.IsDir() {\n    return fmt.Errorf(\"dolt dir %s missing or not a directory\", doltDir)\n}\nif f, err := os.OpenFile(markerPath, os.O_WRONLY|os.O_CREATE, 0600); err != nil {\n    return fmt.Errorf(\"marker %s not writable: %w\", markerPath, err)\n} else {\n    f.Close()\n}","typeGuard":null,"tryCatchPattern":"if err := MarkDoltDirCompatible(doltDir); err != nil {\n    var pathErr *fs.PathError\n    if errors.As(err, &pathErr) && errors.Is(pathErr, os.ErrPermission) {\n        // advise: chown/chmod doltDir for current user\n    }\n    return err\n}","preventionTips":["Run all bd commands as the same user that owns .beads","Do not create .bd-dolt-ok manually; let bd write it with mode 0600","Keep the filesystem holding .beads writable and with free space","After upgrades, verify the marker exists: ls .beads/.bd-dolt-ok"],"tags":["filesystem","permissions","dolt","marker"],"backgroundTag":"dolt-compat-marker-write-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}