phacility/phabricator · warning · PhutilArgumentUsageException

There are no Diviner '%s' files anywhere beneath the current

Error message

There are no Diviner '%s' files anywhere beneath the current directory. Use '%s' to specify a documentation book to generate.

What it means

`diviner generate` can either target an explicit book (`--book path/to/book.book`) or auto-discover books. In discovery mode it runs FileFinder from getcwd() looking for files with the `.book` suffix; if the finder returns nothing, this usage exception is thrown. It means there is no Diviner book configuration anywhere beneath the directory you ran the command in.

Source

Thrown at src/applications/diviner/workflow/DivinerGenerateWorkflow.php:65

    $console = PhutilConsole::getConsole();
    $console->writeErr($message."\n");
  }

  public function execute(PhutilArgumentParser $args) {
    $book = $args->getArg('book');
    if ($book) {
      $books = array($book);
    } else {
      $cwd = getcwd();
      $this->log(pht('FINDING DOCUMENTATION BOOKS'));

      $books = id(new FileFinder($cwd))
        ->withType('f')
        ->withSuffix('book')
        ->find();

      if (!$books) {
        throw new PhutilArgumentUsageException(
          pht(
            "There are no Diviner '%s' files anywhere beneath the current ".
            "directory. Use '%s' to specify a documentation book to generate.",
            '.book',
            '--book <book>'));
      } else {
        $this->log(pht('Found %s book(s).', phutil_count($books)));
      }
    }

    foreach ($books as $book) {
      $short_name = basename($book);

      $this->log(pht('Generating book "%s"...', $short_name));
      $this->generateBook($book, $args);
      $this->log(pht('Completed generation of "%s".', $short_name)."\n");
    }
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

Run `diviner generate` from the directory that contains your `.book` file (or an ancestor of it)
Or point at it explicitly: `diviner generate --book path/to/book.book`
If the project has no book yet, create a minimal `.book` JSON file (name, root, title)

Example fix

# before (run from a directory with no .book beneath it)
diviner generate
# after
diviner generate --book /path/to/project/docs/book.book

Defensive patterns

Strategy: validation

Validate before calling

$books = id(new FileFinder(getcwd()))
  ->withType('f')
  ->withSuffix('book')
  ->find();
if (!$books) {
  // No book beneath cwd: pass --book <path> explicitly instead of letting generate throw.
  $args->getArg('book') || print('No .book files found; pass --book <path>'."\n");
}

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  fwrite(STDERR, $ex->getMessage()."\n");
  exit(1);
}

Prevention

Run `diviner generate` from the project root that contains the .book file
Pin CI jobs to `--book <explicit-path>` so they do not depend on cwd
Commit the .book file and check its presence in CI before the docs job

When it happens

Trigger: Running `diviner generate` without `--book` from a directory whose subtree contains no `*.book` files. Typical when running from an arbitrary checkout that has no Diviner documentation configured.

Common situations: Running generate from the wrong working directory (e.g. `/` or `$HOME` instead of the project with a `.book` file); projects that never set up Diviner docs; renamed or deleted `.book` files after a repo reorganization.

Related errors

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