A Salesforce object can have 40 custom relationship fields. Lookups and master-detail fields count toward the same 40, and no more than 2 of them can be master-detail. Standard relationship fields that come with the object, such as AccountId on Contact or OwnerId, are not part of the count.
The limit usually turns up mid-build as an error on the field you are trying to create. On a large Service Cloud project I worked on, we hit it on Case because every department wanted its own reference field. Knowing the number early is cheaper than redesigning in the middle of a release.
Where to see your real count
Go to Setup > Object Manager > [your object] > Object Limits. The row you want is Custom Relationship Fields, with its usage and the maximum of 40. The same page shows limits that tend to bite at the same time:
| Object limit | Default maximum |
|---|---|
| Custom Relationship Fields (lookup + master-detail) | 40 |
| Master-detail relationships | 2 |
| Active Lookup Filters | 5 |
| Rollup Summary Fields | 25 |
| Custom Fields (all types) | 500, depending on edition |
The relationship, lookup filter, roll-up and custom field figures are what a sandbox reported through the Tooling API's EntityLimit object; the cap of 2 master-detail relationships is a documented platform rule. The Object Limits page in your own org is the number to trust, because edition and installed packages can change what you see.
If you would rather query it, the Tooling API exposes the same data:
SELECT Label, Max, Remaining
FROM EntityLimit
WHERE EntityDefinitionId = 'Case'
Run it with sf data query --use-tooling-api or from the Developer Console with Use Tooling API checked.
Why the limit exists
Every relationship field adds a foreign key that Salesforce has to resolve when records load, enforce in sharing calculations and maintain in indexes. Forty is generous for a well-normalized object. An object with 35 or more relationships is usually doing the job of several objects.
Many lookups pointing at the same small set of parent records also invite data skew, which causes record locking and slow sharing recalculation long before you reach 40.
What to do when you are near 40
Plan as if the limit cannot be raised, and redesign before the request that would push you over it.
- Many-to-many relationships. If you have
Vendor_1__c,Vendor_2__candVendor_3__c, you have a many-to-many relationship. Build a junction object (for exampleCase_Vendor__cwith master-detail fields to Case and Vendor) and remove the numbered lookups. It holds any number of vendors and frees several relationship slots. - Near-duplicate lookups. "Primary Vendor" and "Secondary Vendor" can often become one lookup to a partner object plus a
Role__cpicklist, either on the same object or on a junction record. - Reference-only links. If a field only stores an ID from an outside system and nobody navigates to the record, a text field marked External ID may be enough. It does not count as a relationship field.
- Fields that belong on a child. Department-specific references often belong on a related object that holds that department's data, not on the main record.
Querying across relationships
Each custom relationship gets a relationship name ending in __r, which lets you read parent fields in one query instead of several:
SELECT Id, Name, Account__r.Name, Vendor_Ref__r.Status__c
FROM Custom_Object__c
WHERE Account__r.Industry = 'Manufacturing'
Use __c for the ID value and __r to traverse to the parent. Mixing them up is one of the most common SOQL errors on custom objects.
Summary
- 40 custom relationship fields per object, lookups and master-details combined.
- At most 2 master-detail.
- Standard relationship fields do not count.
- Check Object Manager > Object Limits for the real usage.
- Near the limit, fix the data model with junction objects and consolidated lookups rather than hunting for a workaround.
Leave a Comment