{"record":{"id":"f8a525bc91d7d48c","repo":"gastownhall/beads","slug":"proxy-forcestopunverified-publish-stop-epoch-w","errorCode":null,"errorMessage":"proxy.ForceStopUnverified: publish stop epoch: %w","messagePattern":"proxy\\.ForceStopUnverified: publish stop epoch: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/force_stop.go","lineNumber":68,"sourceCode":"// the record is unchanged. Both flows accept an already-gone recorded\n// process. An unverified live PID is never signaled unless its executable\n// basename is exactly bd or dolt (with an optional .exe suffix) AND its\n// command line scopes it to this workspace; where the platform cannot\n// establish that scope, force-stop refuses rather than guessing.\nfunc ForceStopUnverified(rootDir string, opts ...ForceStopOptions) (ForceStopReport, error) {\n\treport := ForceStopReport{RecordPath: pidfile.Path(rootDir, PIDFileName)}\n\tif len(opts) > 1 {\n\t\treturn report, errors.New(\"proxy.ForceStopUnverified: at most one options value is allowed\")\n\t}\n\ttimeout := shutdownConfirmDeadline\n\tif len(opts) == 1 && opts[0].Timeout != 0 {\n\t\ttimeout = opts[0].Timeout\n\t}\n\tif timeout <= 0 {\n\t\treturn report, fmt.Errorf(\"proxy.ForceStopUnverified: timeout must be positive, got %s\", timeout)\n\t}\n\tif err := advanceStopEpoch(rootDir); err != nil {\n\t\treturn report, fmt.Errorf(\"proxy.ForceStopUnverified: publish stop epoch: %w\", err)\n\t}\n\n\tproxyErr := forceStopRecord(rootDir, LockFileName, PIDFileName, pidfile.KindProxy, timeout, &report)\n\n\tbackendReport := ForceStopReport{RecordPath: pidfile.Path(rootDir, server.PIDFileName)}\n\tbackendErr := forceStopRecord(\n\t\trootDir,\n\t\tserver.LockFileName,\n\t\tserver.PIDFileName,\n\t\tpidfile.KindDoltBackend,\n\t\ttimeout,\n\t\t&backendReport,\n\t)\n\tif backendReport.RecordFound || backendErr != nil {\n\t\treport.Backend = &backendReport\n\t}\n\treturn report, errors.Join(proxyErr, backendErr)\n}","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/force_stop.go#L50-L86","documentation":"ForceStopUnverified publishes a stop epoch to coordinate force-stop attempts, and this error wraps any failure of advanceStopEpoch (e.g. inability to write the epoch file in the database root). It is thrown before any process is signaled, aborting the force-stop so concurrent stop attempts do not proceed uncoordinated.","triggerScenarios":"Calling proxy.ForceStopUnverified when advanceStopEpoch(rootDir) fails — typically a read-only or missing rootDir, permission denied writing the epoch file, or an I/O error on the filesystem holding the workspace.","commonSituations":"Running against a database directory mounted read-only, a wrong rootDir path that does not exist, disk-full conditions, or a container running as a different UID than the directory owner.","solutions":["Verify rootDir exists and is writable by the current user (ls -ld, touch a test file)","Check the wrapped cause (%w) for the underlying os.MkdirAll/WriteFile error and fix permissions or free disk space accordingly","Pass the correct workspace root directory path to ForceStopUnverified","Re-run after the filesystem becomes writable (e.g. remount rw)"],"exampleFix":"// before\nreport, err := proxy.ForceStopUnverified(rootDir)\n// after\nif info, statErr := os.Stat(rootDir); statErr != nil || !info.IsDir() {\n    return fmt.Errorf(\"workspace root %s is not an accessible directory\", rootDir)\n}\nreport, err := proxy.ForceStopUnverified(rootDir)","handlingStrategy":"validation","validationCode":"func rootWritable(dir string) error {\n    info, err := os.Stat(dir)\n    if err != nil {\n        return err\n    }\n    if !info.IsDir() {\n        return fmt.Errorf(\"%s is not a directory\", dir)\n    }\n    return unix.Access(dir, unix.W_OK)\n}","typeGuard":null,"tryCatchPattern":"report, err := proxy.ForceStopUnverified(rootDir)\nif err != nil && strings.Contains(err.Error(), \"publish stop epoch\") {\n    fmt.Fprintf(os.Stderr, \"check %s is writable: %v\\n\", rootDir, err)\n    return err\n}","preventionTips":["Verify the workspace root exists and is writable before force-stop","Avoid read-only or disk-full filesystems for active databases","Keep the epoch/state files owned by the running user","Pass the exact workspace root, not a parent or child path"],"tags":["filesystem","permissions","force-stop","state-file"],"backgroundTag":"file-write-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}