phacility/phabricator · error · Exception

Icon key "%s" is not a valid icon key. Icon keys must be 1-3

Error message

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.

What it means

Each icon's `key` must match /^[a-z]{1,32}\z/: one to thirty-two lowercase ASCII letters, anchored at both ends. Digits, hyphens, underscores, uppercase letters, and keys longer than 32 characters all throw; the message itself suggests 'tag' and 'group' as reasonable keys.

Source

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

          pht(
            'Value for index "%s" should be a dictionary.',
            $idx));
      }

      PhutilTypeSpec::checkMap(
        $value,
        array(
          'key' => 'string',
          'name' => 'string',
          'icon' => 'string',
          'image' => 'optional string',
          'special' => 'optional string',
          'disabled' => 'optional bool',
          'default' => 'optional bool',
        ));

      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(

View on GitHub (pinned to 5720a38cfe)

Solutions

Rename the key to lowercase letters only, 1-32 characters (e.g. "myicon" instead of "My-Icon").
Generate the config programmatically and filter keys with the same regex before saving.

Example fix

// before
{"key": "My-Icon", "name": "My Icon", "icon": "fa-star"}
// after
{"key": "myicon", "name": "My Icon", "icon": "fa-star"}

Defensive patterns

Strategy: validation

Validate before calling

foreach ($config as $entry) {
  if (!preg_match('/^[a-z]{1,32}\z/', $entry['key'])) {
    throw new Exception('icon key must be 1-32 lowercase letters: '.$entry['key']);
  }
}

Type guard

function is_valid_icon_key($key) {
  return is_string($key) && preg_match('/^[a-z]{1,32}\z/', $key) === 1;
}

Prevention

Lowercase and strip non-letters when generating icon keys.
Run the same regex the validator uses before saving config.

When it happens

Trigger: Config entries with keys like "Tag", "my-icon", "group2", or a 33-letter key.

Common situations: Porting kebab-case or mixed-case icon names from other systems into projects.icons.

Related errors

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