phacility/phabricator · error · Exception

Value for "function" argument must be a natural list beginni

Error message

Value for "function" argument must be a natural list beginning with a function name as a string. The first list item has the wrong type, %s.

What it means

For a 'function' argument list, the first element must be the function name as a string; array_shift() extracts it and a non-string first element (int, array, null) throws this Exception reporting the offending type.

Source

Thrown at src/applications/fact/chart/PhabricatorChartFunctionArgument.php:110

        if (!phutil_is_natural_list($value)) {
          throw new Exception(
            pht(
              'Value for "function" argument must be a natural list, not '.
              'a dictionary. Actual value is "%s".',
              phutil_describe_type($value)));
        }

        if (!$value) {
          throw new Exception(
            pht(
              'Value for "function" argument must be a list with a function '.
              'name; got an empty list.'));
        }

        $function_name = array_shift($value);

        if (!is_string($function_name)) {
          throw new Exception(
            pht(
              'Value for "function" argument must be a natural list '.
              'beginning with a function name as a string. The first list '.
              'item has the wrong type, %s.',
              phutil_describe_type($function_name)));
        }

        $functions = PhabricatorChartFunction::getAllFunctions();
        if (!isset($functions[$function_name])) {
          throw new Exception(
            pht(
              'Function "%s" is unknown. Valid functions are: %s',
              $function_name,
              implode(', ', array_keys($functions))));
        }

        return id(clone $functions[$function_name])
          ->setArguments($value);

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Put the function name string first: array('sum', 1, 2).
2. Check ordering when composing lists dynamically — verify is_string($list[0]).
3. Use array_unshift($args, $fn_name) rather than appending the name at the end.
4. Validate JSON specs so nested function nodes start with a string.

Example fix

// before
$arguments[] = array(1, 2, 'sum'); // name in wrong position -> Exception

// after
$arguments[] = array('sum', 1, 2); // function name first, as a string

function list_starts_with_function_name(array $list) {
  return is_string(idx($list, 0));
}

When it happens

Trigger: Passing a list whose first element is not a string, e.g. array(123, 'x'), array(array('sum', 1), 2) (function name position occupied by a nested list), or array(null, ...).

Common situations: Misordered lists where arguments precede the function name; dynamic list building that prepends values in the wrong order; JSON arrays whose first element is a number or another array.

Related errors

• Value for "fact-key" argument must be a string, got %s.
• Value for "number" argument must be an integer or double, go
• Value for "function" argument must be a function definition,
• Value for "function" argument must be a natural list, not a
• Value for "function" argument must be a list with a function

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