Managed Package Uninstall Fails Due to Dependency or Component Reference Error

This article explains how to fix a Salesforce managed package uninstall that fails with a dependency or component reference error. It covers checking permissions, emptying the Recycle Bin, removing component dependencies, and handling "bad reference" errors that require Salesforce Support.

Step 1: Verify You Have the Required Permission

1. From Setup, open your user record.
2. Confirm your profile or a permission set includes Download AppExchange Packages.
3. If the permission is missing, ask your system admin to assign it before proceeding.

Step 2: Empty the Recycle Bin

1. From the App Launcher, open Recycle Bin (or navigate to `/lightning/o/RecycleBin/home`).
2. Click Empty Org Recycle Bin to permanently delete all records.
3. Retry the package uninstall.

Warning: Emptying the Recycle Bin is permanent. Confirm that no records need to be recovered before proceeding.

Step 3: Find and Remove Component Dependencies

Use one of the following methods to identify what is referencing the package:

• Setup → Installed Packages: Click the package name, then click View Dependencies to see all org components that reference the package.
• Workbench: Run a SOQL (Salesforce Object Query Language) query against MetadataComponentDependency to find references. The following example query returns the name and type of each component that references the package namespace: `SELECT MetadataComponentName, MetadataComponentType, RefMetadataComponentName FROM MetadataComponentDependency WHERE RefMetadataComponentNamespace = 'NAMESPACE'`

Once dependencies are identified:

1. For Flows or Process Builders: deactivate and delete the flow/process that references the package.
2. For custom fields: delete the field from Setup → Object Manager.
3. For Apex classes: remove or modify the class to eliminate the package reference.
4. Retry the uninstall after removing each dependency.

Step 4: Escalate for "Bad Reference" Errors

If the dependency view shows no references but the uninstall still fails, the org may have a "bad reference", which is an orphaned metadata reference that cannot be removed through the UI. In this case:

1. Log a case with Salesforce Support, including your org ID and the package namespace.
2. Grant Support login access: Setup → My Personal Information → Grant Account Login Access.
3. Support will use backend tools to remove the orphaned reference and complete the uninstall.

Related Video

FAQ

What is a "bad reference" when the dependency view shows nothing but the managed package uninstall still fails?

A bad reference is an orphaned metadata dependency that the Salesforce UI cannot display or remove. These occur when components are deleted in a way that leaves behind unreferenced pointers. Salesforce Support can remove these using backend tools.

What should I check when the managed package uninstall still fails on one item after I removed all known dependencies?

Check the Recycle Bin for deleted records that might reference the package. Also check for scheduled jobs, email alerts, or workflow rules that reference package objects, because these may not appear in the dependency view.

Can I uninstall a managed package with the Salesforce CLI instead of the UI?

Yes. For 2GP (second-generation) managed packages, you can use the Salesforce CLI (Command Line Interface) command `sf package:uninstall`. This may succeed in cases where the UI uninstall fails, though dependency errors still apply. Contact Salesforce Support if the CLI uninstall also fails.