phacility/phabricator · warning · PhutilArgumentUsageException

Unable to start notifications server because it is already r

Error message

Unable to start notifications server because it is already running. Use `%s` to restart it.

What it means

Thrown by willLaunch() when getPID() returns a live PID from the PID file, meaning an Aphlict instance appears to already be running. Start is refused to avoid two daemons fighting over the same ports and PID file; the message points at `aphlict restart` as the supported path.

Source

Thrown at src/applications/aphlict/management/PhabricatorAphlictManagementWorkflow.php:354

    $extension = new ReflectionExtension($ext);
    foreach ($extension->getFunctions() as $function) {
      $function = $function->name;
      if (!function_exists($function)) {
        echo pht(
          'ERROR: The PHP function %s is disabled. You must '.
          'enable it to run Aphlict on this machine.',
          $function.'()')."\n";
        exit(1);
      }
    }
  }

  final protected function willLaunch() {
    $console = PhutilConsole::getConsole();

    $pid = $this->getPID();
    if ($pid) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to start notifications server because it is already '.
          'running. Use `%s` to restart it.',
          'aphlict restart'));
    }

    if (posix_getuid() == 0) {
      throw new PhutilArgumentUsageException(
        pht('The notification server should not be run as root.'));
    }

    // Make sure we can write to the PID file.
    if (!$this->debug) {
      Filesystem::writeFile($this->getPIDPath(), '');
    }

    // First, start the server in configuration test mode with --test. This
    // will let us error explicitly if there are missing modules, before we

View on GitHub (pinned to 5720a38cfe)

Solutions

Use `bin/aphlict restart` which stops the running instance before starting
If you are sure nothing is running, remove the stale PID file (path from config 'pidfile') and start again
Verify with `ps -p <pid-from-pidfile> -f` whether the recorded PID is really an aphlict/node process before deleting anything

Example fix

# before
$ bin/aphlict start   # -> already running
# after
$ bin/aphlict restart
# or, if the PID file is stale:
$ cat /var/run/aphlict/aphlict.pid; ps -fp $(cat /var/run/aphlict/aphlict.pid)
$ rm /var/run/aphlict/aphlict.pid && bin/aphlict start

Defensive patterns

Strategy: try-catch

Validate before calling

$pid = phutil_getenv('APHLECT_PID');
// shell-level pre-check:
$pid = trim(@file_get_contents('/var/run/aphlict/aphlict.pid'));
if ($pid && posix_kill((int)$pid, 0)) {
  // already running: use restart instead of start
}

Try / catch

try {
  $workflow->willLaunch();
} catch (PhutilArgumentUsageException $ex) {
  if (preg_match('/already running/', $ex->getMessage())) {
    // benign: switch to `aphlict restart` instead of start
  }
}

Prevention

Always use `aphlict restart` in scripts; it handles the running case cleanly
After crashes or reboots, verify and clean stale PID files before automated start

When it happens

Trigger: Running `bin/aphlict start` (or debug without a prior stop) while a previous instance is up; also when a stale PID file names a PID that happens to belong to any currently running process.

Common situations: Server rebooted and the daemon was started by an init script while an operator manually starts it too; a previous crash left a stale PID file whose recorded PID was reused by an unrelated process.

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/a8fa8d9161f5c23e. Report an issue: GitHub.