{"record":{"id":"b6583a64971e0d5b","repo":"gastownhall/beads","slug":"server-doltserver-start-acquire-s-w","errorCode":null,"errorMessage":"server: DoltServer.Start: acquire %s: %w","messagePattern":"server: DoltServer\\.Start: acquire (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/server/doltserver.go","lineNumber":225,"sourceCode":"\t\t\treturn nil\n\t\t}\n\t\tif !isRetryableDoltInitErr(err) {\n\t\t\treturn backoff.Permanent(err)\n\t\t}\n\t\treturn err\n\t}\n\n\treturn backoff.Retry(op, backoff.WithMaxRetries(backoff.WithContext(bo, ctx), maxRetries))\n}\n\nfunc (s *DoltServer) Start(ctx context.Context) error {\n\tif s.eg != nil || s.egCtx != nil {\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: server already started\")\n\t}\n\n\tlock, err := util.TryLock(filepath.Join(s.rootDir, LockFileName))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: acquire %s: %w\", LockFileName, err)\n\t}\n\n\tif err := s.doltConfigure(ctx); err != nil {\n\t\tlock.Unlock()\n\t\treturn err\n\t}\n\n\tif err := s.doltInitWithRetries(ctx); err != nil {\n\t\tlock.Unlock()\n\t\treturn err\n\t}\n\n\targs := []string{\n\t\t\"sql-server\",\n\t\t\"--config\", s.configPath,\n\t}\n\n\tmanagedCtx, cancel := context.WithCancel(context.Background())","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/server/doltserver.go#L207-L243","documentation":"DoltServer.Start could not create the advisory file lock proxy-child.lock in the server's root directory. This library uses the lock to guarantee only one managed dolt sql-server process exists per root dir; TryLock fails when the lock file exists and is held by another process, or the file cannot be created/opened.","triggerScenarios":"Calling Start() when another DoltServer (or a previous uncleanly-terminated process) still holds proxy-child.lock in rootDir; concurrent Start() calls on servers sharing rootDir; rootDir not writable so the lock file cannot be created.","commonSituations":"Two beads instances pointed at the same storage dir; a crashed run left a stale lock owner entry; running the app as a different user without write access to the data directory; read-only filesystem or container volume.","solutions":["Check for another live process using the same rootDir (ps / pgrep for `dolt sql-server`) and stop it, or use a different rootDir.","Verify no stale holder: if no dolt process is running but the lock is reported held, remove the leftover proxy-child.lock and retry.","Check permissions on rootDir; ensure the current user can create and lock files there.","Ensure Start() is not called concurrently for the same rootDir within your application; serialize or use a single server instance."],"exampleFix":"// before\nsrv.Start(ctx) // may fail: proxy-child.lock held\n// after\nif !srv.Running(ctx) {\n    if err := srv.Start(ctx); err != nil {\n        log.Fatalf(\"start server: %v (is another bd instance using this dir?)\", err)\n    }\n}","handlingStrategy":"validation","validationCode":"// Before Start: check the lock is not held by a live process.\nlockPath := filepath.Join(rootDir, \"proxy-child.lock\")\nif lock, err := util.TryLock(lockPath); err != nil {\n    return fmt.Errorf(\"storage dir %s appears to be in use by another process: %w\", rootDir, err)\n} else {\n    lock.Unlock() // release; Start will re-acquire\n}","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"acquire proxy-child.lock\") {\n        // another instance owns this data dir; abort or point at another rootDir\n        return fmt.Errorf(\"data dir busy: %w\", err)\n    }\n    return err\n}","preventionTips":["One process per data directory — enforce in your deployment (supervisors, k8s single-writer).","Check for running `dolt sql-server` processes before starting.","After crashes, verify no stale lock holder before restarting.","Ensure the user running the app owns rootDir."],"tags":["filesystem","locking","process-management"],"backgroundTag":"file-lock-contention","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}