phacility/phabricator · error · PhutilArgumentUsageException

Configuration file is not properly formatted JSON. %s

Error message

Configuration file is not properly formatted JSON. %s

What it means

Thrown by the Aphlict (Phabricator notification server) management workflow when the file given via --config cannot be decoded as JSON. The raw file contents are passed to phutil_json_decode(), and any decode failure is wrapped in this PhutilArgumentUsageException. It signals that the user-supplied config file is syntactically invalid, before any schema or semantic validation happens.

Source

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

    echo tsprintf(
      "%s\n",
      pht(
        'Reading configuration from: %s',
        $show_path));

    try {
      $data = Filesystem::readFile($full_path);
    } catch (Exception $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Failed to read configuration file. %s',
          $ex->getMessage()));
    }

    try {
      $data = phutil_json_decode($data);
    } 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(

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Validate syntax before starting: php -r 'json_decode(file_get_contents("conf/aphlict.json")); echo json_last_error_msg();' or `jq . conf/aphlict.json`
2. Remove comments, trailing commas, and single-quoted strings; make every key a double-quoted JSON string
3. Re-save the file as plain UTF-8 without BOM and confirm it is complete (matching braces)
4. Run `bin/aphlict config --test conf/aphlict.json` (if available in your version) to iterate on config errors safely

Example fix

// conf/aphlict.json — before (invalid: comment + trailing comma)
{
  // notification server
  "servers": [{"type": "client", "port": 22280,},],
}
// after
{
  "servers": [{"type": "client", "port": 22280}],
}

$raw = Filesystem::readFile($config_path);
if (json_decode($raw) === null && json_last_error() !== JSON_ERROR_NONE) {
  throw new InvalidArgumentException(
    'Aphlict config is not valid JSON: '.json_last_error_msg());
}
// or from the shell: jq . conf/aphlict.json > /dev/null

try {
  (new PhabricatorAphlictStartWorkflow())->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // Config/usage error from the admin; print and exit non-zero.
  fwrite(STDERR, $ex->getMessage()."\n");
  exit(1);
}

When it happens

Trigger: Running any bin/aphlict subcommand (start, stop, restart, debug, config) with --config pointing at a file that json_decode rejects: trailing commas, single quotes around strings, // or /* */ comments, unquoted keys, a UTF-8 BOM, or a truncated file.

Common situations: Admins copy a JSON example from a wiki/blog that contains comments, or edit the config in an editor that saves a BOM; CI pipelines generate a truncated file; someone converts an old .conf-style file to JSON and leaves legacy syntax.

Related errors

• Specify a user to notify with "--user".
• No user with username "%s" exists.
• Specify a message to send with "--message".
• Configuration file has improper configuration keys at top le
• Two servers (at indexes "%s" and "%s") both bind to the same

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