The Salesforce Metadata Puzzle: Why Your Record Type Retrieval Feels Incomplete

The Mismatch That Makes You Question Everything 🤔

You're knee-deep in a deployment. Everything looks good. But something doesn't sit right. You open your locally retrieved metadata file and see about 150 lines of record type configuration.

Yet when you peek into Salesforce Setup, you're staring at way more picklist mappings and field-level assignments than what your tool pulled in.

The real kicker?
Your diff tool says you're about to remove fields—like custom loss reasons, business categories, or industry tags—that are still very much alive in the org.

How does that even happen?

The "Standard" Retrieve That Lets You Down 😞

Naturally, most of us do this:

sfdx project retrieve start -m "RecordType:CustomObject__c.My_Record_Type"

You're being precise. Specific. Targeted. It feels correct.
But what you get? A partial slice of reality.
No full picklist context. No dependent field mappings. Just a skeleton.

The Fix That Actually Works ✨

To move from the 150-line confusion to the 220+ lines you expected:

sfdx project retrieve start -m "CustomObject:CustomObject__c" -o your-org-alias

This might feel broader than necessary, but it's the only way to get a truly accurate picture. Here's why this works:

• •Full field context — Includes all fields, even those with record-type-specific behavior
• •Accurate picklist mappings — Pulls both global and record-type-specific values
• •Security-level clarity — Reveals FLS and profile interaction
• •Object dependencies — Picks up related metadata that the record type leans on

The Deeper Truth ✓

Record types are not standalone.
They're metadata overlays—tightly linked to the field definitions, global value sets, business processes, and even profile permissions.

When you retrieve just the record type you might miss:

• •Full picklist context

But when you retrieve the object: You get everything the record type is trying to describe.

A Word of Caution: The Custom Object Gotcha ⚠️

When you retrieve custom object metadata, yes you might get the record types as needed, but that also pulls all the changes on the object. This could be irritating if you're doing manual changes to the object—such as enabling field history tracking on fields—and you're not actively managing that flag through GitHub.

The solution? Remove those other files before you proceed to commit the record type changes you want to push to GitHub. This keeps your commits focused and prevents unintended metadata overwrites.

Debugging Strategy in the Real World 🔧

Here's how we work through this:

1. •🎯 Start with full object retrieval when working on anything involving record types
2. •✅ Always specify your org alias with -o to reduce env mix-ups
3. •📊 Check the line counts between versions—if something's off by a mile, trust your instinct
4. •🔐 Check your user permissions if fields are still "missing"—they might be hidden from you, not gone from the org

The Developer's Takeaway

When Salesforce metadata looks "incomplete," the problem isn't missing data—it's missing context.

Record types are deeply relational. They sit at the intersection of fields, values, visibility, and business logic.