{"record":{"id":"c0eb0a344a18b2a8","repo":"gastownhall/beads","slug":"server-doltserver-start-write-pidfile-w","errorCode":null,"errorMessage":"server: DoltServer.Start: write pidfile: %w","messagePattern":"server: DoltServer\\.Start: write pidfile: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/server/doltserver.go","lineNumber":301,"sourceCode":"\t\tcancel()\n\t\tlock.Unlock()\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: resolve proxy root identity: %w\", err)\n\t}\n\n\tif err := pidfile.Write(s.rootDir, PIDFileName, pidfile.PidFile{\n\t\tPid:    s.pid,\n\t\tPort:   s.config.Port(),\n\t\tSchema: pidfile.SchemaV2,\n\t\tKind:   pidfile.KindDoltBackend,\n\t\tBirth:  string(birth),\n\t\tRootID: rootID,\n\t}); err != nil {\n\t\t_ = cmd.Process.Kill()\n\t\t_, _ = cmd.Process.Wait()\n\t\ts.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0\n\t\tcancel()\n\t\tlock.Unlock()\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: write pidfile: %w\", err)\n\t}\n\n\teg.Go(func() error {\n\t\tdefer lock.Unlock()\n\t\treturn cmd.Wait()\n\t})\n\n\tif err := s.waitReady(ctx); err != nil {\n\t\tcancel()\n\t\t_ = s.eg.Wait()\n\t\ts.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0\n\t\t_ = pidfile.Remove(s.rootDir, PIDFileName)\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: %w\", err)\n\t}\n\treturn nil\n}\n\nfunc (s *DoltServer) waitReady(ctx context.Context) error {","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/server/doltserver.go#L283-L319","documentation":"Start() spawned dolt successfully but failed to write the pidfile (proxy-child.pid) containing pid, port, birth identity and root ID. The pidfile lets other processes discover and validate the managed server, so Start aborts: the child is killed and all state rolled back.","triggerScenarios":"pidfile.Write fails — rootDir not writable, disk full, or a conflicting/locked pidfile left over from a prior crash that cannot be overwritten.","commonSituations":"Read-only or full data volume; permission changes after a previous run (started as root, now running as normal user); stale proxy-child.pid owned by another user in a shared directory.","solutions":["Check disk space (df -h) and that rootDir is writable by the current user.","Remove a stale proxy-child.pid (after confirming no dolt sql-server is running) and retry.","Fix ownership: chown the data directory to the user running beads.","Retry Start() once filesystem issues are resolved."],"exampleFix":"// before\nsrv.Start(ctx) // fails: cannot write proxy-child.pid\n// after\n// as a one-off fix on the machine:\n//   rm -f <rootDir>/proxy-child.pid\n//   chown -R $(whoami) <rootDir>\nif err := srv.Start(ctx); err != nil {\n    log.Fatalf(\"start server: %v\", err)\n}","handlingStrategy":"validation","validationCode":"// Ensure rootDir is writable and disk has free space before Start.\nif !isDirWritable(rootDir) {\n    return fmt.Errorf(\"rootDir %s not writable by current user\", rootDir)\n}\nvar st syscall.Statfs_t\nif err := syscall.Statfs(rootDir, &st); err == nil && st.Bavail*uint64(st.Bsize) < 10<<20 {\n    return fmt.Errorf(\"less than 10MB free on %s; refusing to start\", rootDir)\n}","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"write pidfile\") {\n        // clean stale pidfile only if no dolt process is running, then retry\n        if noDoltRunning() {\n            os.Remove(filepath.Join(rootDir, \"proxy-child.pid\"))\n            return srv.Start(ctx)\n        }\n        return err\n    }\n    return err\n}","preventionTips":["Run all processes touching the data dir as the same user.","Monitor disk space on the data volume.","After crashes, clean stale proxy-child.pid only when no dolt sql-server is alive.","Keep data dirs on local disk, not read-only or flaky mounts."],"tags":["filesystem","pidfile","permissions"],"backgroundTag":"pidfile-write-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}