What causes "Duo username pairing mode ("%s") is not supported." in phacility/phabricator?

Edit the Duo provider in the UI and re-save the 'Duo Username' select (Use Platform Username or Use Primary Email Address).

phacility/phabricator · error · Exception

Duo username pairing mode ("%s") is not supported.

Error message

Duo username pairing mode ("%s") is not supported.

What it means

PhabricatorDuoAuthFactor::getDuoUsername() maps the provider property 'duo.usernames' to the Duo-side username; only 'username' (Phabricator username) and 'email' (primary email address) are implemented, matching the provider edit form's select options. Any other value falls through to default and throws whenever the factor needs to pair a Phabricator user to a Duo user.

Source

Thrown at src/applications/auth/factor/PhabricatorDuoAuthFactor.php:771

      ->setIntegrationKey($duo_key)
      ->setSecretKey($duo_secret)
      ->setAPIHostname($duo_host)
      ->setTimeout(10)
      ->setHTTPMethod('POST');
  }

  private function getDuoUsername(
    PhabricatorAuthFactorProvider $provider,
    PhabricatorUser $user) {

    $mode = $provider->getAuthFactorProviderProperty(self::PROP_USERNAMES);
    switch ($mode) {
      case 'username':
        return $user->getUsername();
      case 'email':
        return $user->loadPrimaryEmailAddress();
      default:
        throw new Exception(
          pht(
            'Duo username pairing mode ("%s") is not supported.',
            $mode));
    }
  }

  private function shouldAllowDuoEnrollment(
    PhabricatorAuthFactorProvider $provider) {

    $mode = $provider->getAuthFactorProviderProperty(self::PROP_ENROLL);
    switch ($mode) {
      case 'deny':
        return false;
      case 'allow':
        return true;
      default:
        throw new Exception(
          pht(

View on GitHub (pinned to 5720a38cfe)

Solutions

Edit the Duo provider in the UI and re-save the 'Duo Username' select (Use Platform Username or Use Primary Email Address).
Inspect the provider properties and reset duo.usernames to 'username' or 'email'.
If the record cannot be repaired, delete and recreate the provider (users re-enroll).

Example fix

// before: hand-edited provider property
"duo.usernames": "userName"
// after: one of the two supported values
"duo.usernames": "username"

Defensive patterns

Strategy: validation

Validate before calling

// Run when saving the provider config.
$mode = $provider->getAuthFactorProviderProperty(
  PhabricatorDuoAuthFactor::PROP_USERNAMES);
if (!in_array($mode, array('username', 'email'), true)) {
  // reject the save; only these two pairing modes are implemented
}

Type guard

function isSupportedDuoUsernameMode($mode) {
  return in_array($mode, array('username', 'email'), true);
}

Prevention

Change provider settings only through the edit UI, never by editing stored properties directly.
After DB migrations or restores, smoke-test each MFA provider.
Keep custom patches and stored config values in sync.

When it happens

Trigger: The duo.usernames provider property contains a value other than 'username'/'email' — hand-edited database, config imported from a different Phabricator version or fork, or a custom extension writing an unsupported value. Thrown during enrollment pairing and challenge issuance.

Common situations: Editing auth_factor_provider properties JSON directly; restoring a dump from a fork that had extra modes; custom patches adding a mode that stored data references but this code version does not implement.

Related errors

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