rohitg00/agentmemory · warning

--force: bypassing Docker-heuristic guard. Falling back to n

Error message

--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.

What it means

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.

Source

Thrown at src/cli.ts:3567

      return;
    }
    const survivors = new Set<number>(portPids);
    if (pidfilePid) survivors.add(pidfilePid);
    if (workerPid) survivors.add(workerPid);
    p.log.warn(
      `Engine not responding on :${port}, but ${survivors.size} process(es) still hold the port or pidfile: ${[...survivors].join(", ")}`,
    );
    p.log.info(
      `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}`,
    );
    process.exit(1);
  }

  if (!state) {
    const compose = discoverComposeFile();
    if (compose && pidfilePid === null) {
      if (force) {
        p.log.warn(
          `--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.`,
        );
      } else {
        p.log.error(
          `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.`,
        );
        process.exit(1);
      }
    }
  }

  const candidates = new Set<number>();
  if (pidfilePid) candidates.add(pidfilePid);
  for (const pid of portPids) candidates.add(pid);

  // stop must also reap the agentmemory worker process
  // (`node dist/index.mjs`). If only the engine is killed, the worker can
  // survive (detached spawn / signal not propagated) and reconnect to the

View on GitHub (pinned to e04ba88819)

Solutions

1. Prefer stopping via compose: docker compose -f <compose-file> down
2. Re-run with AGENTMEMORY_USE_DOCKER=1 so state is recorded for future stops
3. Keep --force only when you verified with lsof what holds the port

Example fix

// before
$ agentmemory stop --force
warn: --force: bypassing Docker-heuristic guard...
// after
$ docker compose -f docker-compose.yml down

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

When it happens

Trigger: `agentmemory stop --force` when discoverComposeFile() found a compose file and pidfilePid is null — the --force path bypasses the Docker-heuristic refusal.

Common situations: Engine started inside docker compose in another terminal/host; state wiped but process alive; user running stop from a different machine/SSH session.

Related errors

• iii-engine binary not available for ${platform()}/${process.
• EPERM
• Engine not responding on :${port}, but ${survivors.size} pro

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/5650b4d9954de694. Report an issue: GitHub.