What breaks when you delete, rename or deactivate a picklist value

The short version

1. Decide between delete, deactivate, replace and relabel, using the table below.
2. Find every component that compares against or writes the value.
3. Update or retire that automation first.
4. Check reports, list views and dashboards that filter on the value.
5. Make the change in a sandbox, run your tests, then repeat in production.

Delete vs deactivate vs replace vs relabel

Sources: Salesforce Help articles on keeping a value for historical records, renaming versus replacing, and replacing a picklist value, plus Trailhead’s Manage Your Picklist Values and picklist basics, which explain that only restricted picklists block values coming from the API and automation.

Why the native tools only get you halfway

“Where is this used?” works per field, not per value. It tells you a Flow references Status. It does not tell you whether that Flow cares about Complete, Cancelled or neither. You have to open each component and read its conditions.

Value references also hide in places that are slow to open:

• Flow entry criteria, Decision outcomes and Get Records filters
• Formula fields and validation rules using ISPICKVAL
• Workflow and approval field updates that set the value
• Criteria-based sharing rules
• Apex that compares the field to a string
• Report filters, list views and Lightning page visibility rules

Step by step, by hand

1. Search retrieved metadata for the value

sf project retrieve start --metadata Flow CustomObject ApexClass ApexTrigger Workflow SharingRules
grep -rn "Complete" force-app/main/default

Expect noise. A common word like “Complete” appears in labels, descriptions and other fields. Check each hit is about the right field on the right object.

2. Open each hit and classify it

Mark each one as “compares against the value” or “writes the value.” Writers matter most on a restricted picklist, because their saves will start failing.

3. Check reports and list views

Reports are not in the search above. Open reports built on the object and look at their filters, or run a report grouped by the field to see how many records hold the value.

4. Decide what happens to existing records

If the value should survive on old records, deactivate it. If it should be merged into another value, replace it. Delete with a blank only when losing the value is fine.

With sf-intelligence

sf-intelligence reads your org’s metadata once, keeps a copy on your computer, and lets your AI assistant answer from it. It never writes to the org. These are real answers from the built-in demo org, a solar installer called Verdant.

Ask: “What breaks if I remove ‘Complete’ from Project Status?” The answer is blocking, with three things that depend on the value:

"verdict": "blocking",
"impacts": [
  { "componentId": "CustomField:Project__c.Is_Complete__c", "category": "metadata-blocker" },
  { "componentId": "Flow:Installation_On_Complete", "category": "metadata-blocker",
    "where": ["writes this value (recordUpdate) — keeps saving a value no longer in the list"] },
  { "componentId": "ValidationRule:Project__c.Complete_Requires_Permit", "category": "metadata-blocker",
    "where": ["criteria: ISPICKVAL(Status__c,\"Complete\") && NOT(Permit_Approved__c)"] }
],
"restricted": false

Ask: “What if I remove ‘Approved’?” One blocker: the Project_On_Approve Flow, which only starts when Status equals Approved. That Flow creates the Permit record, so permits would stop being created.

Ask: “What if I remove ‘Cancelled’?” The answer is risky, and it names the Share_Projects_To_Ops sharing rule. That rule shares every project whose Status is not Cancelled with the Ops group. If you replace Cancelled with another value, the cancelled projects start being shared with Ops.

What to check by hand, even with the tool

Each answer lists what it did not check. For this field it named report and dashboard filters, path assistants, Flow screen visibility rules, dependent-picklist matrices, and Apex that compares a variable or uses dynamic SOQL.

Apex needs a manual search. The demo’s ProjectTriggerHandler copies Status into a variable and compares it to every value, including ‘Complete’, ‘Approved’ and ‘Cancelled’. None of the answers above listed it, because a comparison through a variable is on the “not checked” list. Search your Apex for the value text before you change the list.

Checklist before you change a picklist value

1. List every Flow, formula, validation rule, sharing rule and workflow that uses the value.
2. Search Apex for the value as a string.
3. Check reports, dashboards and list views that filter on it.
4. Check record types and dependent picklists that list it.
5. Decide: deactivate, replace or delete.
6. Update the automation first, then change the value, in a sandbox.
7. Run your Apex tests and walk through the affected Flows.
8. Repeat in production and tell report owners.