phacility/phabricator · error · Exception

Constraint "phids" to "transaction.search" requires nonempty

Error message

Constraint "phids" to "transaction.search" requires nonempty list, empty list provided.

What it means

In the transaction.search Conduit method, constraints.phids is typed 'optional list<string>', but an explicitly empty list is meaningless for an IN-style filter and is rejected with a plain Exception. idx() distinguishes null (key absent) from array() (present but empty), so only the explicit empty-array case throws. Omit the key entirely when there is no PHID constraint.

Source

Thrown at src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php:306

    return $this->addPagerResults($results, $pager);
  }

  private function applyConstraints(
    array $constraints,
    PhabricatorApplicationTransactionQuery $query) {

    PhutilTypeSpec::checkMap(
      $constraints,
      array(
        'phids' => 'optional list<string>',
        'authorPHIDs' => 'optional list<string>',
      ));

    $with_phids = idx($constraints, 'phids');

    if ($with_phids === array()) {
      throw new Exception(
        pht(
          'Constraint "phids" to "transaction.search" requires nonempty list, '.
          'empty list provided.'));
    }

    if ($with_phids) {
      $query->withPHIDs($with_phids);
    }

    $with_authors = idx($constraints, 'authorPHIDs');
    if ($with_authors === array()) {
      throw new Exception(
        pht(
          'Constraint "authorPHIDs" to "transaction.search" requires '.
          'nonempty list, empty list provided.'));
    }

    if ($with_authors) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Build the constraints map conditionally: only set phids when the list is nonempty.
Pass at least one real PHID if you genuinely want the filter.
Fix client helper code that merges empty defaults into request payloads.

Example fix

// before
$params = array('constraints' => array('phids' => $phids));
// after
$params = array('constraints' => array());
if ($phids) {
  $params['constraints']['phids'] = $phids;
}

Defensive patterns

Strategy: validation

Validate before calling

// strip empty constraint lists before the conduit call
$constraints = array();
if ($phids) {
  $constraints['phids'] = $phids;
}
$parameters = array('constraints' => $constraints);

Type guard

// PHP: only nonempty string lists may be sent as phids
function isValidPhidList($value) {
  return $value === null
    || (is_array($value) && count($value) > 0
        && !in_array('', $value, true));
}

Try / catch

Catch the conduit error client-side, detect 'requires nonempty list' with the constraint name in the message, then re-send once with empty-list constraints removed — this is safe because the error is raised before any query executes.

Prevention

Never serialize empty arrays into constraints; drop the key instead.
Centralize constraint building in one helper that filters empty lists.

When it happens

Trigger: Calling transaction.search with constraints: {"phids": []} — typically a client that always includes the field and serializes its own empty filter list.

Common situations: Generated API clients (arc call-conduit, Python/JS wrappers) that serialize empty arrays instead of dropping the key; UI code forwarding an empty multi-select as an empty list.

Related errors

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