Loading

Managed Package Uninstall Fails Due to Dependency or Component Reference Error

Date de publication: Jul 1, 2026
Description

Common error messages: "You can't uninstall this package because components in your org reference it." or "Uninstall failed due to unresolved reference."

Cause
Custom Components Reference the Package

Components you created outside the package — such as custom fields, Flows, Process Builders, custom buttons, or Apex classes — may reference objects or fields from the managed package. Salesforce prevents uninstall until all such references are removed.

Items in the Recycle Bin Reference the Package

Deleted records or components in your Recycle Bin may still hold references to package objects. The uninstall process checks the Recycle Bin for references and fails if any are found.

Missing "Download AppExchange Packages" Permission

The user performing the uninstall must have the Download AppExchange Packages permission. Without it, the uninstall option is not available.

Résolution
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 query against MetadataComponentDependency to find references. Example: 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" — 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.
FAQ
Q: The dependency view shows nothing, but the uninstall still fails. What is a "bad reference"?
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.
Q: I removed all the dependencies I can find, but the uninstall still fails on one item. What should I check?
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 — these may not appear in the dependency view.
Q: Can I uninstall a managed package via CLI instead of the UI?
Yes. For 2GP managed packages, you can use the Salesforce CLI command sf package:uninstall. This may succeed in cases where the UI uninstall fails, though dependency errors still apply. Contact Salesforce Support if CLI uninstall also fails.
Numéro d’article de la base de connaissances

005388258

 
Chargement
Salesforce Help | Article