phacility/phabricator · error · Exception

The project image ("%s") specified for ("%s") was not found

Error message

The project image ("%s") specified for ("%s") was not found in the folder "resources/builtin/projects/".

What it means

An icon spec with an `image` attribute must reference a file shipped under resources/builtin/projects/ and enumerated by PhabricatorFilesOnDiskBuiltinFile::getProjectBuiltinFiles(). The validator builds the absolute path (library root + resources/builtin/projects/ + name) and checks it against the flipped builtin map; a miss throws. Arbitrary custom images cannot be used through config alone.

Source

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

            $key));
      } else {
        $keys[$key] = true;
      }

      $is_disabled = idx($value, 'disabled');

      $image = idx($value, 'image');
      if ($image !== null) {
        $builtin = idx($value, 'image');
        $builtin_map = id(new PhabricatorFilesOnDiskBuiltinFile())
          ->getProjectBuiltinFiles();
        $builtin_map = array_flip($builtin_map);

        $root = dirname(phutil_get_library_root('phabricator'));
        $image = $root.'/resources/builtin/projects/'.$builtin;

        if (!array_key_exists($image, $builtin_map)) {
            throw new Exception(
              pht(
                'The project image ("%s") specified for ("%s") '.
                'was not found in the folder "resources/builtin/projects/".',
                $builtin,
                $key));
        }
      }

      if (idx($value, 'default')) {
        if ($default === null) {
          if ($is_disabled) {
            throw new Exception(
              pht(
                'The project icon marked as the default icon ("%s") must not '.
                'be disabled.',
                $key));
          }
          $default = $value;

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Drop the `image` key and style the icon with a Font Awesome name in `icon` instead.
2. Point `image` at one of the shipped builtin filenames in resources/builtin/projects/.
3. To ship a real custom image, add the file to resources/builtin/projects/ and register it in the builtin map (fork or extension work).

Example fix

// before
{"key":"custom","name":"Custom","icon":"fa-star","image":"myicon.png"}
// after
{"key":"custom","name":"Custom","icon":"fa-star"}

$root = dirname(phutil_get_library_root('phabricator'));
foreach ($config as $entry) {
  $image = idx($entry, 'image');
  if ($image !== null &&
      !file_exists($root.'/resources/builtin/projects/'.$image)) {
    // drop the image key, or ship + register the file first
  }
}

When it happens

Trigger: "image": "myicon.png" where the file is not present in resources/builtin/projects/ or is not registered in the builtin file map.

Common situations: Trying to add custom project images purely via config, and forks that renamed or removed builtin image files.

Related errors

• 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
• Icon special attribute "%s" is not valid. Recognized special
• 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/793104cfa0d6517a. Report an issue: GitHub.