On a rare occasion things may not go as planned. You may see an install failure email like from Salesforce or an error message directly on the page:

Your request to install package "Pharos X.XXX" was unsuccessful. None of the data or setup information in your salesforce.com organization was affected.

If your install continues to fail, contact Salesforce CRM Support through your normal channels and provide the following information.

So far we know of only two issues that have affected more than a single customer. If you are seeing a different problem, please reach out to us and we'll be happy to provide assistance.

Dependent class is invalid and needs recompilation

This error is usually very scary because of the verbose error message. Here's a snipped of what you might see on your end:

1.  Dependent class is invalid and needs recompilation:
Class pharos.ConfigUtil : Dependent class is invalid and needs recompilation:
Class pharos.JiraService : Dependent class is invalid and needs recompilation:
Class pharos.GraphAPIService : Dependent class is invalid and needs recompilation:
Class pharos.Logger : Dependent class is invalid and needs recompilation:
Class pharos.PassthroughtModeService : Dependent class is invalid and needs recompilation:
Class pharos.BulkAPIJobBatchService : Dependent class is invalid and needs recompilation:
Class pharos.LogService : Dependent class is invalid and needs recompilation:
Class pharos.LogPostProcessingService : Dependent class is invalid and needs recompilation:
Class pharos.BroadcastService : Dependent class is invalid and needs recompilation:
Class pharos.ConnectedOrgService : Dependent class is invalid and needs recompilation:
Class pharos.AdminService : Dependent class is invalid and needs recompilation:
Class pharos.AdminController : Dependent class is invalid and needs recompilation:
Class pharos.GitHubUtils : Dependent class is invalid and needs recompilation:
Class pharos.GitHubCommitBatch : Invalid type: SetupAuditTrail
.........

What Does this Error Mean? 

Simply put, your org happens to be one of the "lucky" ones that doesn't have API access to the SetupAuditTrail object. Pharos utilizes this object to provide an audit trail snapshot on Log details page. It's very helpful for quicker troubleshooting and saves time digging through the CSV export of the audit trail. It is unclear why most orgs are provisioned with this permission, while others aren't.  Just to be clear, this is not a setting that can be enabled by Salesforce users. This is something that Salesforce controls on their backend. From what we've been able to gather, this issue mostly affects newer orgs (provisioned after 2021). If your org is older and still presents with the same problem during the install, the resolution is still the same. 

The Solution

The bad news is that you do have to reach out to Salesforce support and get them to turn on API access for the audit trail.
The good news is that it has been done before and is guaranteed to alleviate the problem you’re seeing.

So, let's get started!

We'll need to create a case from the Salesforce help and training portal. Here's what we suggest you should communicate to the support team:

Description:
We are unable to view SetupAuditTrail object via API. It is not visible in workbench, however it is visible via UI. Because of this we are not able to install a required manage package. Please enable Setup Audit Trail API setting on Salesforce side.

Product: Sales
Severity Level: Severity 2 - Major functionality impacted and time-sensitive
Topic: Developer Support
Attachment: Feel free to attach the error message referenced above.
---------------

Now, support may come back to you and say that you need developer or premier support, to which you can simply reply that you don’t need developer support, just please enable the setting.
They may also ask you to recompile apex classes and run all apex tests. If that's the case please indulge them and tell them that it had no effect (it won't).

We're sorry to make you jump through hoops 😔. Typically the max turn around from Salesforce is 1-2 days and you should be up and running pretty quickly. If you have trouble communicating with Salesforce support do let us know and we'll be happy to help there.

Once Salesforce reports back that they've enabled this permission, please re-try the package installation and, if successful, feel free to close the case.

User Doesn't Have Permission to Create Dashboard With Colors

This problem usually presents itself in the following way:

1. (Issues/Issues) User doesn't have permission (changeDashboardColors) to create dashboard with colors
Issues/Issues: User doesn't have permission (changeDashboardColors) to create dashboard with colors

2. (Pharos_Logs/Admin_Log_Dashboard) User doesn't have permission (changeDashboardColors) to create dashboard with colors
Pharos_Logs/Admin_Log_Dashboard: User doesn't have permission (changeDashboardColors) to create dashboard with colors

3. (Pharos_Logs/Developer_Dashboard) User doesn't have permission (changeDashboardColors) to create dashboard with colors
Pharos_Logs/Developer_Dashboard: User doesn't have permission (changeDashboardColors) to create dashboard with colors
......

What Does this Error Mean? 

This error indicates that the user who's installing Pharos doesn't have the permission called Change Dashboard Colors. This permission allows users to control the color schemes of a dashboard. You can read more about this functionality in this Salesforce knowledge article.

The Solution

Luckily, this one is straightforward, for the most part. All you need to do is assign your user the Change Dashboard Colors permission either at the profile level or at the permission level. If you're having trouble assigning this permission at the profile level as a System Administrator, please refer to this Salesforce knowledge article.

Platform Cache Partitions (Missing Feature)

This problem usually presents itself in the following way:

What Does this Error Mean? 

This error indicates that the organization that's installing Pharos doesn't have the caching feature enabled. Pharos utilizes platform cache for performance reasons. All Salesforce production editions are equipped with some cache capacity, which is typically more than enough for Pharos to function. However, some lightweight Salesforce editions (such as scratch, dev and pre-release) will not come with preconfigured cache partitions. 

The Solution

This one is fairly straightforward. All you need to do is request a trial capacity as described in Salesforce help here.

To read more about Platform Cache Partitions please refer to this Salesforce knowledge article.