{"record":{"id":"78604c553183a732","repo":"nsqio/nsq","slug":"failed-to-lock-data-path-v","errorCode":null,"errorMessage":"failed to lock data-path: %v","messagePattern":"failed to lock data-path: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nsqd/nsqd.go","lineNumber":108,"sourceCode":"\t\tstartTime:            time.Now(),\n\t\ttopicMap:             make(map[string]*Topic),\n\t\texitChan:             make(chan int),\n\t\tnotifyChan:           make(chan interface{}),\n\t\toptsNotificationChan: make(chan struct{}, 1),\n\t\tdl:                   dirlock.New(dataPath),\n\t}\n\tn.ctx, n.ctxCancel = context.WithCancel(context.Background())\n\thttpcli := http_api.NewClient(nil, opts.HTTPClientConnectTimeout, opts.HTTPClientRequestTimeout)\n\tn.ci = clusterinfo.New(n.logf, httpcli)\n\n\tn.lookupPeers.Store([]*lookupPeer{})\n\n\tn.swapOpts(opts)\n\tn.errValue.Store(errStore{})\n\n\terr = n.dl.Lock()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to lock data-path: %v\", err)\n\t}\n\n\tif opts.MaxDeflateLevel < 1 || opts.MaxDeflateLevel > 9 {\n\t\treturn nil, errors.New(\"--max-deflate-level must be [1,9]\")\n\t}\n\n\tif opts.ID < 0 || opts.ID >= 1024 {\n\t\treturn nil, errors.New(\"--node-id must be [0,1024)\")\n\t}\n\n\tif opts.TLSClientAuthPolicy != \"\" && opts.TLSRequired == TLSNotRequired {\n\t\topts.TLSRequired = TLSRequired\n\t}\n\n\ttlsConfig, err := buildTLSConfig(opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build TLS config - %s\", err)\n\t}","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/nsqio/nsq/blob/85cf10c09c6c3c86160d6f0eb156f62d0efc1648/nsqd/nsqd.go#L90-L126","documentation":"nsqd takes an exclusive flock (LOCK_EX|LOCK_NB, see internal/dirlock) on its data directory at startup to guarantee a single writer per --data-path. This error means the lock could not be acquired: most commonly another live nsqd already owns the directory (the underlying error text says 'possibly in use by another instance of nsqd'), or the directory could not even be opened (missing, not a directory, no permissions).","triggerScenarios":"Starting a second nsqd with the same --data-path; the directory does not exist or nsqd's user lacks read permission on it; a supervising system (systemd restart, Docker retry) launching a replacement before the old process fully exited and released the flock.","commonSituations":"Copy-pasting a unit file for a second node without changing --data-path; accidental double-start via service manager plus manual run; k8s liveness probe storm causing overlapping restarts; moving data-path to a mount that is not yet mounted (path missing).","solutions":["Find the other holder: pgrep -a nsqd, fuser -v /var/lib/nsqd, then stop it or give this instance its own --data-path","Verify the directory exists, is a directory, and is readable/writable by the nsqd user: ls -ld /var/lib/nsqd","If using restart wrappers, add a pre-start check that waits for the old pid to exit","In containers, ensure the volume is mounted before nsqd starts"],"exampleFix":"# before (two instances, same path)\nnsqd --data-path=/var/lib/nsqd\nnsqd --data-path=/var/lib/nsqd   # second start -> failed to lock data-path\n\n# after\nnsqd --data-path=/var/lib/nsqd-a\nnsqd --data-path=/var/lib/nsqd-b","handlingStrategy":"try-catch","validationCode":"// pre-start: ensure path exists and is not already locked\nif fi, err := os.Stat(dataPath); err != nil || !fi.IsDir() {\n\tlog.Fatalf(\"data path %s missing or not a directory\", dataPath)\n}","typeGuard":null,"tryCatchPattern":"n, err := nsqd.New(opts)\nif err != nil {\n\tif strings.Contains(err.Error(), \"failed to lock data-path\") {\n\t\t// another nsqd owns the directory (or path unopenable):\n\t\t// stop the other instance or use a distinct --data-path; do not retry in place\n\t}\n\tlog.Fatal(err)\n}","preventionTips":["Give every nsqd instance a unique --data-path (and --node-id)","Ensure the data directory is mounted before the service starts","Use start-limit / pre-stop semantics so restarts never overlap the flock window"],"tags":["nsqd","startup","file-lock","data-path","concurrency"],"backgroundTag":null,"analyzedSha":"85cf10c09c6c3c86160d6f0eb156f62d0efc1648","analyzedAt":"2026-08-16T00:53:05.009Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}