phacility/phabricator · warning · PhutilArgumentUsageException

Specify a Diviner book configuration file with %s.

Error message

Specify a Diviner book configuration file with %s.

What it means

DivinerWorkflow::readBookConfiguration() loads and validates the `.book` JSON that every Diviner workflow needs. When it is called with a null path — i.e. no `--book` was given — it throws this PhutilArgumentUsageException immediately, before touching the filesystem. Workflows such as `atomize` require `--book` explicitly because they have no discovery fallback.

Source

Thrown at src/applications/diviner/workflow/DivinerWorkflow.php:22

  private $config;
  private $bookConfigPath;

  public function getBookConfigPath() {
    return $this->bookConfigPath;
  }

  protected function getConfig($key, $default = null) {
    return idx($this->config, $key, $default);
  }

  protected function getAllConfig() {
    return $this->config;
  }

  protected function readBookConfiguration($book_path) {
    if ($book_path === null) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify a Diviner book configuration file with %s.',
          '--book'));
    }

    $book_data = Filesystem::readFile($book_path);
    $book = phutil_json_decode($book_data);

    PhutilTypeSpec::checkMap(
      $book,
      array(
        'name' => 'string',
        'title' => 'optional string',
        'short' => 'optional string',
        'preface' => 'optional string',
        'root' => 'optional string',
        'uri.source' => 'optional string',
        'rules' => 'optional map<regex, string>',

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add `--book <path>` pointing at your `.book` file: `diviner atomize --book docs/book.book ...`
2. Verify the path is readable before running: `cat docs/book.book`
3. If invoking programmatically, never pass null; resolve the book path first

Example fix

# before
diviner atomize --atomizer DivinerPHPAtomizer src/
# after
diviner atomize --book docs/book.book --atomizer DivinerPHPAtomizer src/

if ($args->getArg('book') === null) {
  // atomize has no discovery fallback: require an explicit --book path.
  $args->printHelpAndExit();
}

When it happens

Trigger: Running `diviner atomize` (or any workflow that calls readBookConfiguration($args->getArg('book'))) without the `--book` flag. Note that `generate` only hits this if it auto-discovers nothing or is invoked programmatically with a null book path.

Common situations: Assuming all workflows auto-discover books like `generate` does; scripts that call the workflow classes directly and pass a null path; renaming the `.book` file and not updating the command.

Related errors

• Specify an atomizer class with %s.
• Specify one or more files to atomize.
• Request parameter "%s" is not formatted properly. Expected a
• Config option "phd.user" is not set. You must set this optio
• Specify a public key to revoke trust for with --id.

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