> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/the-basics/upgrade.md).

# Upgrade

Upgrade an existing Pharos installation to a new major release — install over the current package, redeploy permission sets, reset the running user, verify.

This page covers a **major release upgrade** of an existing Pharos installation — for example, moving an org already running Pharos to Pharos 2.0. Salesforce delivers patch releases automatically; this page is the procedure for major release upgrades, not for patch pushes.

An upgrade is the same installer run over the package you already have. There is **no uninstall, no teardown, and no preparatory cleanup** — your logs, issues, rules, integration settings, and connected orgs stay where they are.

What an upgrade does **not** do for you, and why this page exists:

* **Pharos permission sets are not part of the managed package**, so no release ever updates them. You redeploy and reassign them yourself. (Triton's permission sets do ship in the Triton package — see step 3.)
* **The running user context needs re-establishing** after the upgrade, so Pharos's schedulers and email service run as the user you intend.
* **Triton's platform-event subscriber user** must be set again if Triton is installed.

{% hint style="danger" %}
**Triton has an order of its own: upgrade Pharos first, then Triton, then re-assign Triton's permission sets (steps 2 and 4).** Triton 2.0 requires Pharos 2.284.5 or later, and moving from Triton 1.x to 2.0 is a breaking upgrade — read step 2 before you start.
{% endhint %}

***

## Before You Begin

* **Decide who the running user will be.** The upgrade uses the same running user concept as a fresh install — see [Choosing the Right User](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md#choosing-the-right-user).
* **Have the permission set ZIP ready** — [pharos-permissions](https://resources.pharos.ai/pharos-permissions).

{% hint style="info" %}
**Best Practice:** Always upgrade your sandbox first, verify everything works as expected, then upgrade production.
{% endhint %}

***

## Upgrade Steps

{% stepper %}
{% step %}

### Identify the running user

Decide which user Pharos will run as after the upgrade — the same decision you made at install time, and usually the same user. **Log in as that user** before you start, because the reset in step 5 always applies to whoever is logged in.

For the concept, the permissions involved, and the trade-off between an admin account and a dedicated integration user, see [Pharos Running User](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md).
{% endstep %}

{% step %}

### Install the latest package over the existing one

There is no separate upgrade URL. The same install links and the AppExchange listing always point to the current version, and running the installer against an org that already has Pharos performs the upgrade in place.

Use the link matching your environment — [production](https://resources.pharos.ai/pharos-prod) or [sandbox](https://resources.pharos.ai/pharos-sandbox) — and follow the standard installer flow described in [Package Installation](https://docs.pharos.ai/configuration-guide/the-basics/package-installation.md). For sandbox specifics, see [Sandbox Installation](https://docs.pharos.ai/configuration-guide/the-basics/package-installation.md#sandbox-installation).

If Triton is installed, upgrade the Triton package in the same pass, **after** Pharos — it ships and versions separately from Pharos, and Triton 2.0 requires Pharos 2.284.5 or later. The Triton package includes Triton's permission sets. See [Installing Pharos Triton](https://triton.pharos.ai/installing-pharos-triton).

{% hint style="danger" %}
**Triton 2.0 is a breaking upgrade from 1.x.** There is no compatibility layer:

* `Triton.instance` is gone — Triton 2.0 has a static API.
* The Integration, Warning, Event, and Debug log categories are removed. Apex that references them, or `Triton.instance`, no longer compiles.
* Log Level rules keyed on a removed category stop matching. Re-key them to a Level or to a technology category.
* Logging methods now buffer: a log is published only when `Triton.flush()` runs. Use `Triton.logNow(...)` where 1.x published immediately.

Migrate your code with the [migrate-to-2.0 agent skill](https://triton.pharos.ai/instrumentation-skills/migrate-to-2.0), and run the whole upgrade in a sandbox first. See [Migrating from 1.x](https://triton.pharos.ai/migration) for the method-by-method mapping.
{% endhint %}
{% endstep %}

{% step %}

### Redeploy the permission sets

Pharos permission sets ship **separately from the managed package**, as a downloadable ZIP: [pharos-permissions](https://resources.pharos.ai/pharos-permissions). They carry user permissions such as View All Data, which Salesforce does not allow inside packaged metadata — so upgrading the package never updates them. Download, unzip, and deploy the `pharos-permissions` folder with your preferred tool. See [Obtaining the Permission Sets](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md#obtaining-the-permission-sets) for the details.

If you use Triton, there is nothing extra to deploy here: Triton's permission sets — `Triton_End_User`, `Triton_Read`, and `Triton_Write` — ship inside the Triton package, so the Triton upgrade in step 2 already updated them. Only if you install Triton from source do you deploy them yourself, from the same Triton release and **after** the rest of Triton, never before. See [Configure Permissions](https://triton.pharos.ai/installing-pharos-triton#configure-permissions) in the Triton docs.

{% hint style="warning" %}
**Deploying Triton from source? A permission set from a newer Triton release fails against an older Triton.** `Triton_Read` and `Triton_Write` grant field access on the Log object, and the fields they name are deployed by Triton itself — each release can add more. Deployed into an org still running an older Triton, they name a field that org does not have yet and the deployment errors out on the invalid field. If you hit this, finish the Triton upgrade in step 2 and deploy again — nothing needs undoing.
{% endhint %}
{% endstep %}

{% step %}

### Assign the permission sets to the user

Redeploying a permission set does not disturb who it is already assigned to — existing assignments survive. Assign **Log\_Admin** to the running user if it is not already assigned.

Triton is the exception: **after a Triton upgrade, its permission sets have to be re-assigned.** Until you re-assign them, the field access the new release added is not visible to your users. Re-assign `Triton_Read` and `Triton_Write` to everyone who had them before the upgrade — see [Configure Permissions](https://triton.pharos.ai/installing-pharos-triton#configure-permissions) for what each set grants.
{% endstep %}

{% step %}

### Reset the running user

Navigate to **Pharos Admin → Advanced → Pharos Running User** and click **Reset**.

**Reset always applies to the user you are currently logged in as** — there is no user picker on the screen. Confirm the current-user line reads the user you intend before clicking. See [Pharos Running User](https://docs.pharos.ai/configuration-guide/advanced/pharos-running-user.md) for the screen in detail.

{% hint style="info" %}
**What Reset changes:** it re-points **`PharosLogServiceSchedulerMode1`**, **`PharosLogServiceSchedulerMode2`**, and the **email service context user**. It does **not** re-parent every Pharos scheduled job — any separately scheduled Pharos job keeps its original submitter, and you reschedule those yourself if they need to move to the new user.
{% endhint %}
{% endstep %}

{% step %}

### Update the Triton platform-event subscriber user

**Skip this step if Triton is not installed.**

Go to **Pharos Admin → Advanced → Triton → Configuration → Platform Event**. The tab has four cards: **Select an Active User** (Save), **Suspend Platform Event Subscription** (Suspend), **Resume Platform Event Subscription** (Resume), and **Run a Test** (Test). Set the subscriber user on the **Select an Active User** card and click **Save**. For how the suspend, resume, and test cards fit together, follow the Triton docs linked below.

This is the subscriber for Triton's `Log_Event__e` platform event. It is **not** the Issue Tracker's `AI_Event__e` context user, which is configured separately — changing one does not change the other.

For the full walkthrough, see [Installing Pharos Triton](https://triton.pharos.ai/installing-pharos-triton).
{% endstep %}

{% step %}

### Verify with Quick Test

Open **Pharos Admin → Quick Start**, choose **Fresh Install**, and click **Launch**. Re-running the wizard against an already-configured org is safe. Work through the ribbon — **Remote Settings → Connect an Org → Error Tracking → Quick Test** — to the final step, **Quick Test**.

Quick Test sends a synthetic exception email and polls for the resulting Log record, confirming the inbound email → email service → parser → `Log__c` path works after the upgrade. It does **not** exercise Triton or platform events — for those, use the **Run a Test** card from step 6.

{% hint style="warning" %}
**Do not choose Sandbox Refresh to verify an upgrade.** That option is only for an org that has just been refreshed from production. It deletes the package email service addresses, deletes the remote site settings Pharos created, deletes your connected orgs, clears connected-org settings, and deactivates every active rule except Archival. Running it after an upgrade is destructive.
{% endhint %}

See [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) for the wizard in full.
{% endstep %}
{% endstepper %}

***

## Troubleshooting

| Issue                                                                                                                                                                                                           | Cause                                                                                                                                                                                  | Resolution                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Triton permission set deploy fails with an invalid-field error on a Log object field                                                                                                                            | Triton is being deployed from source, and the permission sets are from a newer Triton release than the Triton installed in the org, so they name a field that version has not deployed | Upgrade Triton (step 2), deploy the permission sets again, then re-assign them (step 4)                                                                                                              |
| Triton permission sets missing after installing Triton                                                                                                                                                          | Triton was deployed from source without its permission sets — the Triton package always includes them                                                                                  | Deploy them from the same Triton release — see [Configure Permissions](https://triton.pharos.ai/installing-pharos-triton#configure-permissions)                                                      |
| Users lack access, or the fields a new Triton release adds are not visible, even though the permission sets deployed                                                                                            | Deploying does not assign — and a Triton upgrade requires its sets to be re-assigned                                                                                                   | Re-assign `Triton_Read` and `Triton_Write` to the users who had them before the upgrade (step 4)                                                                                                     |
| Reset applied to the wrong user                                                                                                                                                                                 | Reset targets the logged-in user; there is no picker                                                                                                                                   | Log in as the intended running user and click **Reset** again                                                                                                                                        |
| Some background jobs still show the previous submitter                                                                                                                                                          | Reset covers the Mode1/Mode2 schedulers and the email service context only                                                                                                             | Reschedule those jobs as the new running user — see [Pharos Running User](https://docs.pharos.ai/configuration-guide/advanced/pharos-running-user.md)                                                |
| Triton logs stop arriving after the upgrade                                                                                                                                                                     | Platform-event subscriber user not set after the upgrade                                                                                                                               | Complete step 6 — set the subscriber user, then follow the Triton docs for the platform-event subscription                                                                                           |
| Quick Test fails with a deliverability banner                                                                                                                                                                   | Sandbox email deliverability is restricted                                                                                                                                             | See the Quick Test guidance in [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md)                                                                                              |
| After upgrading from an earlier Pharos version, such as 1.x, a connected org shows **Connection invalid**, with a log saying it *"was created by an earlier Pharos version and can no longer be authenticated"* | Carried-over connections normally keep working, but this one's original connected app can no longer authenticate it                                                                    | Delete the connection and set it up again. See [Connections from an earlier Pharos version](https://docs.pharos.ai/configuration-guide/connected-orgs.md#connections-from-an-earlier-pharos-version) |

***

## Not Covered Here

* **Sandbox refresh** — a refreshed sandbox needs the **Sandbox Refresh** option in [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md), which is a different (and destructive) operation from an upgrade.
* **Removed log categories** — Pharos 2.0 removes the severity-shaped categories (Error, Warning, Debug, Event). Rules and mappings keyed on them keep matching legacy logs but match nothing from upgraded producers, so re-key them after upgrading — see [Log Categories](https://docs.pharos.ai/configuration-guide/advanced/log-categories.md).
* **Removing Pharos** — see [Uninstall](https://docs.pharos.ai/configuration-guide/the-basics/uninstall.md).

***

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📥 Package Installation</strong></td><td>The installer flow, sandbox installs, and install troubleshooting</td><td><a href="https://docs.pharos.ai/configuration-guide/the-basics/package-installation.md">Package Installation</a></td></tr><tr><td><strong>👤 Pharos Running User</strong></td><td>Concept, required permissions, choosing the right user</td><td><a href="https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md">Pharos Running User</a></td></tr><tr><td><strong>👤 Pharos Running User (Advanced)</strong></td><td>The Reset screen and what it changes</td><td><a href="https://docs.pharos.ai/configuration-guide/advanced/pharos-running-user.md">Pharos Running User</a></td></tr><tr><td><strong>🚀 Quick Start</strong></td><td>The wizard ribbon and Quick Test</td><td><a href="https://docs.pharos.ai/configuration-guide/quick-start.md">Quick Start</a></td></tr></tbody></table>
