Deployment

Cannot change field type from <type1> to <type2> via the API

Salesforce restricts which field type changes are allowed in a deploy. Many type transitions (Number to Text, Picklist to Lookup, Text to Long Text Area, etc.) require a UI-based wizard with data migration. The deploy fails until you make the change via the UI or a destructive-create cycle.

Also seen asCannot change field type·field type cannot be changed·field type change not allowed

Salesforce field-type changes have three classes:

Allowed automatically in deploy — small changes like Text length increase, picklist value additions
Allowed but with caveats — Text → Long Text Area, Number precision changes (in some directions)
Not allowed via API — anything that would lose data or change the underlying storage

Hit class 3 in a deploy and you get this error.

Allowed via API

From → To	Notes
Text(50) → Text(100)	Length increase, fine
Number(10,2) → Number(12,2)	Precision increase, fine
Picklist (add values)	Adding values is fine
Restricted Picklist toggle off	Turn off Restricted, fine

Not allowed via API (need UI or destructive)

From → To	Why
Text → Long Text Area	Different storage
Long Text Area → Text	Data truncation risk
Number → Text	Different storage
Picklist → Multi-Select Picklist	Different storage shape
Picklist → Lookup	Underlying type change
Lookup → Master-Detail	Major behavior change
Master-Detail → Lookup	Same — children un-cascade
Encrypted toggle	One-way change

How to do an unsupported change

Option 1: UI wizard

For changes the platform supports interactively, use the Setup → Object → Fields → field → Change Field Type wizard. The platform walks you through data migration, asks which value to use for converted records, etc.

After the change, retrieve the new field metadata from the org and replace your repo's version.

Option 2: Destructive-create cycle

For genuinely unsupported changes:

Create a new field with the new type (e.g., Description_New__c)

Migrate data with a one-shot Apex job:

List<Account> accounts = [SELECT Id, Description, Description_New__c FROM Account];
for (Account a : accounts) {
    a.Description_New__c = a.Description == null ? null : a.Description.left(255);
}
update accounts;

Repoint code to use the new field
Delete the old field (destructive change)
Rename Description_New__c → Description__c (or just keep the new name)

Each step is a separate deploy. The data migration step typically runs in a sandbox first.

A subtle case: API version changes

Some field types were added in specific API versions. If your deploy uses a sourceApiVersion older than the type's introduction, you may see this error. Bump the version.

For example, Time fields are API 50.0+. Deploying a Time field with API 49.0 fails.

When the error is misleading

Sometimes the platform reports "Cannot change field type" when the actual issue is something else — a related dependency, a profile permission, etc. Read the full error message, not just the headline. Salesforce often includes a more specific reason after the headline.

Avoid type changes by design

Custom Metadata Types and Custom Settings are more flexible than custom fields for changing schemas. If you anticipate a field type might change, store it as Custom Metadata from the start.