Salesforce Development · Configuration

Custom Settings vs Custom Metadata Types in Salesforce

Both let you store configuration instead of hard-coding it in Apex or Flow. The big difference is simple: custom metadata records deploy with your code, while custom settings records are data that has to be recreated in every org. That one fact decides most choices.

Side-by-side comparison

Which one should you use?

Start from what the value is for:

Reading them in Apex

Custom metadata

// Get one record by its DeveloperName
Tax_Rule__mdt rule = Tax_Rule__mdt.getInstance('California');
Decimal rate = rule.Rate__c;

// Get all records as a map keyed by DeveloperName
Map<String, Tax_Rule__mdt> rules = Tax_Rule__mdt.getAll();

Hierarchy custom setting

// Returns the most specific value: user, then profile, then org default
Automation_Bypass__c bypass = Automation_Bypass__c.getInstance();
if (bypass.Skip_Triggers__c) {
    return;
}

In a formula or validation rule

// Custom metadata
$CustomMetadata.Tax_Rule__mdt.California.Rate__c

// Hierarchy custom setting
$Setup.Automation_Bypass__c.Skip_Validation__c

Common mistakes

• Expecting custom setting values to deploy. A change set moves the custom setting definition, but production starts with no records. Add loading the values to your deployment steps, or switch to custom metadata.
• Tests failing in production only. Code that reads a custom setting gets nothing in a test unless the test inserts the record first.
• Trying to update custom metadata with DML. It throws an error. Use Metadata.Operations.enqueueDeployment if you truly need runtime updates, or rethink whether it should be a custom setting.
• Storing credentials in either one. Admins and sometimes users can read these values. Use Named Credentials and External Credentials instead.

Common questions