phacility/phabricator · error · PhutilArgumentUsageException

Config option "phd.user" is not set. You must set this optio

Error message

Config option "phd.user" is not set. You must set this option so the private key can be stored with the correct permissions.

What it means

Usage exception from `bin/almanac register`: the Phabricator config option phd.user is empty. The workflow must chown the copied private key and identity files to the daemon user so the phd daemons (and the host identity they manage) can read them, so registration refuses to continue without that configuration.

Source

Thrown at src/applications/almanac/management/AlmanacManagementRegisterWorkflow.php:87

          'No such device "%s" exists!', $raw_device));
    }

    $private_key_path = $args->getArg('private-key');
    if (!strlen($private_key_path)) {
      throw new PhutilArgumentUsageException(
        pht('Specify a private key with --private-key.'));
    }

    if (!Filesystem::pathExists($private_key_path)) {
      throw new PhutilArgumentUsageException(
        pht('No private key exists at path "%s"!', $private_key_path));
    }

    $raw_private_key = Filesystem::readFile($private_key_path);

    $phd_user = PhabricatorEnv::getEnvConfig('phd.user');
    if (!$phd_user) {
      throw new PhutilArgumentUsageException(
        pht(
          'Config option "phd.user" is not set. You must set this option '.
          'so the private key can be stored with the correct permissions.'));
    }

    $tmp = new TempFile();
    list($err) = exec_manual('chown %s %s', $phd_user, $tmp);
    if ($err) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to change ownership of an identity file to daemon user '.
          '"%s". Run this command as %s or root.',
          $phd_user,
          $phd_user));
    }

    $stored_public_path = AlmanacKeys::getKeyPath('device.pub');
    $stored_private_path = AlmanacKeys::getKeyPath('device.key');

View on GitHub (pinned to 5720a38cfe)

Solutions

Set the daemon user: bin/config set phd.user <daemon-user> (commonly 'phd-daemon' or a dedicated account), then rerun register.
Make sure that user exists on the host (getent passwd <daemon-user>) before registering.
Verify you are configuring the same instance the CLI targets (check PHABRICATOR_ENV / phabricator.env when multiple exist).

Example fix

# before
$ bin/almanac register --device web-001 --private-key ./device.key
Usage Exception: Config option "phd.user" is not set. ...

# after
$ bin/config set phd-user phd-daemon   # or: bin/config set phd.user phd-daemon per version
$ bin/almanac register --device web-001 --private-key ./device.key

Defensive patterns

Strategy: validation

Validate before calling

$phd_user = PhabricatorEnv::getEnvConfig('phd.user');
if (!strlen((string)$phd_user)) {
  throw new RuntimeException(
    'phd.user is not set; run: bin/config set phd.user <daemon-user>');
}

Try / catch

# shell preflight before any register
bin/config get phd.user | grep -q . || bin/config set phd.user phd-daemon

Prevention

Include `bin/config set phd.user ...` in the standard Almanac/cluster bootstrap script.
Validate required config (phd.user, almanac namespaces) as a preflight step in provisioning.
After instance migrations/upgrades, diff config against your baseline.

When it happens

Trigger: Fresh install where phd.user was never set; bin/config set phd.user executed against a different instance/environment than the one register runs against; the config was reverted during an upgrade or migration.

Common situations: New cluster builds following the 'Almanac Cluster' setup docs, which require phd.user before registering devices; multi-instance servers where the wrong PHABRICATOR_ENV picks a config without the setting;容器化 deployments that regenerate config and drop the option.

Related errors

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