phacility/phabricator · error · PhutilArgumentUsageException

Configuration file has improper configuration keys at top le

Error message

Configuration file has improper configuration keys at top level. %s

What it means

Thrown when the decoded Aphlict config JSON passes syntax checks but its top-level structure fails PhutilTypeSpec::checkMap() against the allowed schema: 'servers' (required list), 'logs' and 'cluster' (optional lists), 'pidfile' (required string), 'memory.hint' (optional int). It fires on unknown keys, missing required keys, or wrong value types at the top level.

Source

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

    } catch (Exception $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Configuration file is not properly formatted JSON. %s',
          $ex->getMessage()));
    }

    try {
      PhutilTypeSpec::checkMap(
        $data,
        array(
          'servers' => 'list<wild>',
          'logs' => 'optional list<wild>',
          'cluster' => 'optional list<wild>',
          'pidfile' => 'string',
          'memory.hint' => 'optional int',
        ));
    } catch (Exception $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Configuration file has improper configuration keys at top '.
          'level. %s',
          $ex->getMessage()));
    }

    $servers = $data['servers'];
    $has_client = false;
    $has_admin = false;
    $port_map = array();
    foreach ($servers as $index => $server) {
      PhutilTypeSpec::checkMap(
        $server,
        array(
          'type' => 'string',
          'port' => 'int',
          'listen' => 'optional string|null',
          'ssl.key' => 'optional string|null',

View on GitHub (pinned to 5720a38cfe)

Solutions

Diff your config's top-level keys against: servers, logs, cluster, pidfile, memory.hint — remove or fix anything else
Ensure "servers" is a JSON array ([...]) of server objects and "pidfile" is a string path
Quote the literal key "memory.hint" and give it an integer value, e.g. "memory.hint": 512

Example fix

// before
{
  "servers": [...],
  "pid-file": "/var/run/aphlict.pid",
  "memory.hint": "512"
}
// after
{
  "servers": [...],
  "pidfile": "/var/run/aphlict.pid",
  "memory.hint": 512
}

Defensive patterns

Strategy: validation

Validate before calling

$data = phutil_json_decode($raw);
PhutilTypeSpec::checkMap(
  $data,
  array(
    'servers' => 'list<wild>',
    'logs' => 'optional list<wild>',
    'cluster' => 'optional list<wild>',
    'pidfile' => 'string',
    'memory.hint' => 'optional int',
  ));

Type guard

function aphlict_config_has_valid_top_level(array $data) {
  $allowed = array('servers','logs','cluster','pidfile','memory.hint');
  foreach (array_keys($data) as $key) {
    if (!in_array($key, $allowed, true)) { return false; }
  }
  return isset($data['servers']) && is_array($data['servers'])
    && isset($data['pidfile']) && is_string($data['pidfile']);
}

Try / catch

try {
  PhutilTypeSpec::checkMap($data, $spec);
} catch (Exception $ex) {
  // Surface which key failed and fix before launch.
  throw new PhutilArgumentUsageException('Bad config keys: '.$ex->getMessage());
}

Prevention

Keep a known-good config in version control and diff against it after edits
After Phabricator upgrades, re-check config key names in the example config for renames

When it happens

Trigger: Top-level config contains a key not in {servers, logs, cluster, pidfile, memory.hint}; 'servers' or 'pidfile' is missing; 'servers' is a hash/object instead of a list; 'pidfile' is not a string; 'memory.hint' is a string like "512" instead of an integer.

Common situations: Upgrading Phabricator after config key renames (older configs used different key names), typos like "pid-file" or "server", or writing "memory.hint": "256" out of habit from other tools that accept strings.

Related errors

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