phacility/phabricator · warning · PhutilArgumentUsageException

Specify a source with %s.

Error message

Specify a source with %s.

What it means

The most basic guard in NuanceManagementWorkflow::loadSource(): every source-driven nuance management command requires --source, and the helper throws PhutilArgumentUsageException when the argument value has zero length. It exists so commands fail fast with a clear message instead of querying with an empty selector.

Source

Thrown at src/applications/nuance/management/NuanceManagementWorkflow.php:9

<?php

abstract class NuanceManagementWorkflow
  extends PhabricatorManagementWorkflow {

  protected function loadSource(PhutilArgumentParser $argv, $key) {
    $source = $argv->getArg($key);
    if (!strlen($source)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify a source with %s.',
          '--'.$key));
    }

    $query = id(new NuanceSourceQuery())
      ->setViewer($this->getViewer())
      ->setRaisePolicyExceptions(true);

    $type_unknown = PhabricatorPHIDConstants::PHID_TYPE_UNKNOWN;

    if (ctype_digit($source)) {
      $kind = 'id';
      $query->withIDs(array($source));
    } else if (phid_get_type($source) !== $type_unknown) {
      $kind = 'phid';
      $query->withPHIDs($source);
    } else {

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass a source selector: --source <ID> (numeric), --source <PHID> (PHID-NUAN-...), or --source <name>.
2. In scripts, guard before invoking: fail the script when the variable is empty rather than calling bin/nuance with a blank flag.
3. List valid sources first (bin/nuance ... or the Nuance web UI) to get an exact ID/name.

Example fix

# before:
# bin/nuance import --source ""
# -> err: 'Specify a source with --source.'

# after:
# bin/nuance import --source 12

# script guard:
[ -z "$SOURCE" ] && { echo 'SOURCE not set' >&2; exit 2; }
bin/nuance import --source "$SOURCE"

// Script-side guard before building the command:
if (!strlen(trim((string)$source_selector))) {
  throw new Exception('nuance commands require --source <id|phid|name>');
}
$cmd = sprintf('bin/nuance import --source %s', escapeshellarg($source_selector));

When it happens

Trigger: Invoking any subclass workflow that calls loadSource($args, 'source') (e.g. bin/nuance import) without --source, or with an empty value ('--source ""'). strlen($source) == 0 triggers the throw before any query runs.

Common situations: New operators unaware the flag is mandatory; scripts where a $SOURCE shell variable is unset/empty and the command interpolates to '--source '; CI pipelines reusing a command template across projects where only some set the variable.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Specify a commit to extract the diff from.
• Specify an atomizer class with %s.
• Specify a rule to edit with "--rule <id|monogram>".
• Use flags to specify at least one edit to apply to the rule
• Specify an object to test rules for with "--object".

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