phacility/phabricator · error · PhutilArgumentUsageException

Failed to create directory "%s" for specified PID file. You

Error message

Failed to create directory "%s" for specified PID file. You should manually create this directory or choose a different PID file location. %s

What it means

Thrown at the end of Aphlict config validation when creating the parent directory of the configured 'pidfile' fails (Filesystem::createDirectory threw). This is the same pattern as the log-directory check, applied to the PID file location, with the underlying FilesystemException message appended.

Source

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

            'once (at indexes "%s" and "%s"). Each peer must have a '.
            'unique host and port combination.',
            $peer_key,
            $peer_map[$peer_key],
            $index));
      }
    }

    $this->configData = $data;
    $this->configPath = $full_path;

    $pid_path = $this->getPIDPath();
    try {
      $dir = dirname($pid_path);
      if (!Filesystem::pathExists($dir)) {
        Filesystem::createDirectory($dir, 0755, true);
      }
    } catch (FilesystemException $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Failed to create directory "%s" for specified PID file. You '.
          'should manually create this directory or choose a different '.
          'PID file location. %s',
          $dir,
          $ex->getMessage()));
    }
  }

  final public function getPIDPath() {
    return $this->configData['pidfile'];
  }

  final public function getPID() {
    $pid = null;
    if (Filesystem::pathExists($this->getPIDPath())) {
      $pid = (int)Filesystem::readFile($this->getPIDPath());
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pre-create and hand over the directory: sudo mkdir -p /var/run/aphlict && sudo chown <aphlict-user> /var/run/aphlict (make it part of the service startup, since /run is tmpfs)
2. Or use a user-writable pidfile path such as /var/tmp/aphlict.pid or a systemd RuntimeDirectory
3. With systemd, prefer RuntimeDirectory=aphlict over a static pidfile path

Example fix

# before: "pidfile": "/var/run/aphlict/aphlict.pid", dir missing
sudo mkdir -p /var/run/aphlict && sudo chown aphlict:aphlict /var/run/aphlict
# after: bin/aphlict start proceeds

$dir = dirname($config['pidfile']);
if (!Filesystem::pathExists($dir) && !is_writable(dirname($dir))) {
  throw new InvalidArgumentException("Cannot create PID directory {$dir}: check permissions");
}

When it happens

Trigger: "pidfile": "/var/run/aphlict/aphlict.pid" with /var/run/aphlict not existing and the service user lacking permission to create directories under /var/run (root-owned in most distros).

Common situations: Moving the pidfile under /var/run for init/systemd integration while running aphlict as a non-root user; /run being a tmpfs wiped on reboot so the directory disappears after restarts.

Related errors

• Failed to create directory "%s" for specified log file (with
• Unable to start notifications server because it is already r
• Configuration file "%s" exists, but could not be read.
• Failed to open output file "%s" for writing.
• Unable to change ownership of an identity file to daemon use

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