phacility/phabricator · error · ConduitException

API Method "%s" defines a disallowed parameter, "%s". This p

Error message

API Method "%s" defines a disallowed parameter, "%s". This parameter name is reserved.

What it means

ConduitCall's constructor checks every parameter a method declares in defineParamTypes() against ConduitAPIMethod::getParameterMetadataKey(). Names starting with 'api.', plus access_token, scope, output, __conduit__, code, and params, are reserved for protocol metadata and alternate decoding pathways — a method defining one would let clients inject transport-level data, so construction aborts.

Source

Thrown at src/applications/conduit/call/ConduitCall.php:26

 *   $result = $call->execute();
 *
 */
final class ConduitCall extends Phobject {

  private $method;
  private $handler;
  private $request;
  private $user;

  public function __construct($method, array $params, $strictly_typed = true) {
    $this->method = $method;
    $this->handler = $this->buildMethodHandler($method);

    $param_types = $this->handler->getParamTypes();

    foreach ($param_types as $key => $spec) {
      if (ConduitAPIMethod::getParameterMetadataKey($key) !== null) {
        throw new ConduitException(
          pht(
            'API Method "%s" defines a disallowed parameter, "%s". This '.
            'parameter name is reserved.',
            $method,
            $key));
      }
    }

    $invalid_params = array_diff_key($params, $param_types);
    if ($invalid_params) {
      throw new ConduitException(
        pht(
          'API Method "%s" does not define these parameters: %s.',
          $method,
          "'".implode("', '", array_keys($invalid_params))."'"));
    }

    $this->request = new ConduitAPIRequest($params, $strictly_typed);

View on GitHub (pinned to 5720a38cfe)

Solutions

Rename the offending parameter to something not in the reserved set (e.g. 'output' -> 'outputFormat')
Filter generated parameter specs against ConduitAPIMethod::getParameterMetadataKey() before shipping them
Add a unit test that constructs each new method via ConduitCall so reserved names fail in CI, not production

Example fix

// before
public function defineParamTypes() {
  return array(
    'output' => 'required string',
  );
}

// after
public function defineParamTypes() {
  return array(
    'outputFormat' => 'required string',
  );
}

Defensive patterns

Strategy: validation

Validate before calling

foreach (array_keys($param_types) as $key) {
  if (ConduitAPIMethod::getParameterMetadataKey($key) !== null) {
    throw new Exception(
      'Parameter name reserved by conduit protocol: '.$key);
  }
}

Try / catch

try {
  $call = new ConduitCall($method_name, $params);
} catch (ConduitException $ex) {
  // Method-definition bug: fail the developer's test run with the message.
  $this->fail('Reserved parameter name in '.$method_name.': '.$ex->getMessage());
}

Prevention

Learn the reserved set: 'api.*' prefixes plus access_token, scope, output, __conduit__, code, params
Add a CI test that instantiates every ConduitAPIMethod through ConduitCall to catch bad specs early
When generating method specs from schemas, filter keys through getParameterMetadataKey()

When it happens

Trigger: Writing a ConduitAPIMethod subclass whose defineParamTypes() returns a spec containing e.g. 'params', 'code', 'output', 'scope', 'access_token', or any 'api.*' key; the exception fires the first time that method is constructed by a ConduitCall.

Common situations: Newly authored conduit methods during development (the error appears in tests or the first live call); wrappers that build parameter specs from external schemas without filtering reserved words; methods refactored so a user-facing parameter got renamed to a reserved name.

Related errors

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