{"record":{"id":"5650b4d9954de694","repo":"rohitg00/agentmemory","slug":"force-bypassing-docker-heuristic-guard-falling","errorCode":null,"errorMessage":"--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.","messagePattern":"--force: bypassing Docker-heuristic guard\\. Falling back to native pidfile \\+ lsof on :(.+?)\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/cli.ts","lineNumber":3567,"sourceCode":"      return;\n    }\n    const survivors = new Set<number>(portPids);\n    if (pidfilePid) survivors.add(pidfilePid);\n    if (workerPid) survivors.add(workerPid);\n    p.log.warn(\n      `Engine not responding on :${port}, but ${survivors.size} process(es) still hold the port or pidfile: ${[...survivors].join(\", \")}`,\n    );\n    p.log.info(\n      `Preserving ~/.agentmemory/iii.pid + worker.pid. Investigate before manual cleanup:\\n  ps -p ${[...survivors].join(\",\")} -o pid,ppid,comm,etime\\n  ${IS_WINDOWS ? \"netstat -ano | findstr :\" + port : \"lsof -i :\" + port}`,\n    );\n    process.exit(1);\n  }\n\n  if (!state) {\n    const compose = discoverComposeFile();\n    if (compose && pidfilePid === null) {\n      if (force) {\n        p.log.warn(\n          `--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.`,\n        );\n      } else {\n        p.log.error(\n          `Engine is running on :${port} but no pidfile or state file is present. It may have been started via Docker compose by a different shell. Refusing to signal host PIDs.\\n\\nStop it with:\\n  docker compose -f ${compose} down\\n\\nOr re-run with --force to signal whatever lsof finds on :${port}, or AGENTMEMORY_USE_DOCKER=1 to record state next time.`,\n        );\n        process.exit(1);\n      }\n    }\n  }\n\n  const candidates = new Set<number>();\n  if (pidfilePid) candidates.add(pidfilePid);\n  for (const pid of portPids) candidates.add(pid);\n\n  // stop must also reap the agentmemory worker process\n  // (`node dist/index.mjs`). If only the engine is killed, the worker can\n  // survive (detached spawn / signal not propagated) and reconnect to the","sourceCodeStart":3549,"sourceCodeEnd":3585,"githubUrl":"https://github.com/rohitg00/agentmemory/blob/e04ba88819c365c9acf9d6661ea802143e728bd6/src/cli.ts#L3549-L3585","documentation":"Error guard in the stop flow: an engine appears to be listening on the port, but no pidfile or state file exists, suggesting it was started via Docker compose from a different shell/host context. The CLI refuses to signal host PIDs it did not record, unless --force or AGENTMEMORY_USE_DOCKER=1 is used.","triggerScenarios":"`agentmemory stop --force` when discoverComposeFile() found a compose file and pidfilePid is null — the --force path bypasses the Docker-heuristic refusal.","commonSituations":"Engine started inside docker compose in another terminal/host; state wiped but process alive; user running stop from a different machine/SSH session.","solutions":["Prefer stopping via compose: docker compose -f <compose-file> down","Re-run with AGENTMEMORY_USE_DOCKER=1 so state is recorded for future stops","Keep --force only when you verified with lsof what holds the port"],"exampleFix":"// before\n$ agentmemory stop --force\nwarn: --force: bypassing Docker-heuristic guard...\n// after\n$ docker compose -f docker-compose.yml down","handlingStrategy":"validation","validationCode":"if [ -z \"$(cat ~/.agentmemory/iii.pid 2>/dev/null)\" ] && lsof -i :49134 -sTCP:LISTEN; then echo \"Port held but no pidfile — likely docker compose; use: docker compose down\"; fi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start the engine via the official CLI so state files are recorded","Set AGENTMEMORY_USE_DOCKER=1 when running under docker compose","Record which compose project started the engine before stopping it"],"tags":["docker","process","force-flag","stop"],"backgroundTag":"docker-container-process-management","analyzedSha":"e04ba88819c365c9acf9d6661ea802143e728bd6","analyzedAt":"2026-08-30T01:07:40.754Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}