phacility/phabricator · error · Exception

Icon special attribute "%s" is not valid. Recognized special

Error message

Icon special attribute "%s" is not valid. Recognized special attributes are: %s.

What it means

The optional `special` attribute assigns an icon a special role. The only recognized value in this revision is "milestone" (PhabricatorProjectIconSet::SPECIAL_MILESTONE); any other non-null value throws, and the message lists the recognized names by imploding the valid map.

Source

Thrown at src/applications/project/icon/PhabricatorProjectIconSet.php:239

      if (!preg_match('/^[a-z]{1,32}\z/', $value['key'])) {
        throw new Exception(
          pht(
            'Icon key "%s" is not a valid icon key. Icon keys must be 1-32 '.
            'characters long and contain only lowercase letters. For example, '.
            '"%s" and "%s" are reasonable keys.',
            $value['key'],
            'tag',
            'group'));
      }

      $special = idx($value, 'special');
      $valid = array(
        self::SPECIAL_MILESTONE => true,
      );

      if ($special !== null) {
        if (empty($valid[$special])) {
          throw new Exception(
            pht(
              'Icon special attribute "%s" is not valid. Recognized special '.
              'attributes are: %s.',
              $special,
              implode(', ', array_keys($valid))));
        }
      }
    }

    $default = null;
    $milestone = null;
    $keys = array();
    foreach ($config as $idx => $value) {
      $key = $value['key'];
      if (isset($keys[$key])) {
        throw new Exception(
          pht(
            'Project icons must have unique keys, but two icons share the '.

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Remove the `special` attribute, or set it to "milestone" on exactly the icon used for milestones.
2. Treat the value list in the error message as authoritative for your revision.

Example fix

// before
{"key":"milestone","name":"Milestone","icon":"fa-flag","special":"epic"}
// after
{"key":"milestone","name":"Milestone","icon":"fa-flag","special":"milestone"}

$valid_specials = array('milestone' => true);
foreach ($config as $entry) {
  $special = idx($entry, 'special');
  if ($special !== null && empty($valid_specials[$special])) {
    throw new Exception('unknown icon special: '.$special);
  }
}

function is_valid_icon_special($special) {
  return $special === null || in_array($special, array('milestone'), true);
}

When it happens

Trigger: Adding "special": "default" or "special": "tag" to an icon specification in projects.icons.

Common situations: Guessing attribute names, and copying config written for a Phabricator version that recognizes more special roles.

Related errors

• Task status ("%s") has unrecognized value for "locked" confi
• Configuration must be a list of project icon specifications.
• Value for index "%s" should be a dictionary.
• Icon key "%s" is not a valid icon key. Icon keys must be 1-3
• Project icons must have unique keys, but two icons share the

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