Salesforce makes this process very difficult, and despite advice given by great guys on here I have become incredibly frustrated trying to make this work.

I am trying to change a custom objects API name (from Account_health__c to Asset_Health__c) that was very poorly chosen by a predecessor.

1st attempt: Simply change the API name in the object settings

Hahahah of course that won't work, Salesforce wouldn't do something useful like auto-update references for you, or wait for deploying from the sandbox before checking reference integrity. THAT WOULD BE TOO REASONABLE.

2nd attempt: Comment out apex references first in order to change the object API name

Nope, multiple editors/IDEs seem to stall on the saving process for any of these 'comment out' changes, including Aside.io, mavensmate and Salesforce's dev console. There seems to be some issue with commenting all but the top level class declaration of a class. Instead of saving the changes or throwing a save error, they stall indefinitely on 'Saving' then eventually throw metadata container errors when you try to cancel/resave. Great stuff.

3rd attempt: Pull all related class and object metadata, edit and deploy as package so they all update at once.

Here's the thing - How do I actually change the existing object's API name via metadata without creating a NEW object?

It's so frustrating! There is no 'label' or 'api Name' keys in the xml for the object. The API name of the object is determined by the name of the metadata file itself. But if I change the object's filename, it won't update the existing object, it will just create a new one!

Please help guys, its comical how frustratingly difficult they've made this process.

  • Are you also commenting out the curly braces ({})? You need those.
    – Adrian Larson
    Commented Jan 18, 2017 at 22:10
  • No, I'm leaving the braces. It's an empty class with a bunch of commented code in it. As in Public Class classname{}
    – smohyee
    Commented Jan 18, 2017 at 22:13
  • If any of the below answers addressed your problem, please consider accepting one by clicking on the check mark/tick to the left of the answer, turning it green. This marks the question as resolved to your satisfaction, and awards reputation both to you and the person who answered. If you have >= 15 reputation points, you may also upvote the answer if you wish. There is no obligation to do either.
    – Adrian Larson
    Commented Feb 8, 2017 at 3:25
  • @AdrianLarson I upvoted them all but I ended up just not bothering because SF makes it so hard to make this change, so I'm not sure which is the best answer here =/
    – smohyee
    Commented Feb 22, 2017 at 21:04

3 Answers 3


I think developers just become resigned to how painful simple refactoring like changing a name is after a while, either accepting the pain involved or choosing to just leave the bad name. Or choosing to move to a different platform.

(A Java project in an IDE naturally gets broken as you refactor and being able to work through the various changes and then eliminate errors is a natural way to work. Yes consistency checking is good but not when it blocks intermediate work steps.)

My general strategy could be summarised as:

  1. add
  2. change references to the new
  3. migrate data from old to new (if necessary)
  4. then delete the old

This works for SObjects, SObject fields, and Apex. With a local copy of everything grabbed by an IDE, a copy of an SObject with a different name but the same fields can be made. And at least global search and replace can be used to do the change part consistently.

This approach avoids nasty situations in Apex where there are circular references. I've seen colleagues struggle for hours with compilation errors (often not clearly reported by the platform when the circular reference is indirect) when e.g. changing a constructor or method name. The add/change/delete approach keeps the code compiling (and therefore deploying) through each step.


Its true that pushing changes which have different API name existing in target org will result into new component.

It looks like the only ways is in following these three steps:-

  1. Deploy the commented code using any deployment tool example, ANT Force.com migration tool

  2. Change the API name manually

  3. Deploy uncommented code as step 1, referencing the new API name.

However, I am looking for better answer than this.

  • Oh man that is so depressing! Does SF really not have any way to refactor API names short of effectively removing then replacing all references?
    – smohyee
    Commented Jan 18, 2017 at 22:20
  • 2
    They really don't.
    – Adrian Larson
    Commented Jan 18, 2017 at 22:21
  • @AdrianLarson Am I being unreasonable in thinking this is a huge pain and gap in their developer tools?
    – smohyee
    Commented Jan 18, 2017 at 22:25
  • I will be really happy if there is better way
    – Ashwani
    Commented Jan 18, 2017 at 22:26
  • You're being a tad bit unreasonable, yes. If you build code on top of a metadata component, you need to be prepared to face the consequences. Namely, you'll have to remove that code reference before changing the metadata. It's actually a useful feature and has a lot of benefits.
    – Adrian Larson
    Commented Jan 18, 2017 at 22:27

If you can (may or may not be feasible), I prefer the "orbital nuke" path when I need to just Get It Done.

Step 1: Clear Page Metadata References

Change all of your pages by commenting out all previous code and leaving just the following in its place:


If the page uses a standard controller, leave only (replace ... as appropriate):

<apex:page standardController="..."></apex:page>

If the page uses a StandardSetController, leave only:

<apex:page standardController="..." recordSetVar="xyz"></apex:page>

Deploy all these new pages.

Step 2: Clear All Component Metadata References

Replace all components with:


Deploy all these new components.

Step 3: Delete All Triggers and Classes

Prepare a destructiveChanges.xml file that includes the names of all local classes and triggers. Deploy this destructive change.

Step 4: Rename Object

Now, you can safely rename your object. Other types of non-code metadata shouldn't block renaming the object.

Step 5: Put All Your Code Back

You should be able to deploy your triggers, classes, components, and pages all in one fell swoop, thankfully. You can even use a change set if you've got one prepared in advance.

So, you're looking at about four deployments, or a really long, annoying weekend. Nuking all of your code, fixing the problem, and redeploying is really the only surefire way to just Get It Done.

Trying to mess with commenting/etc is pretty painful.

I recommend using a few trial sandboxes to test the process out in advance.

Note: Using a change set for the last step is essential if you decide to delete all your classes; you'll need to restore your classes security access for all profiles. Use a recent copy of production, and deploy the profiles alongside all the elements to restore their security settings.

  • User dont want to delete
    – Ashwani
    Commented Jan 18, 2017 at 22:28
  • @Ashwani I know they don't want to, but this is the most effective method I can think of. Deleting (almost) all of the code and redeploying it is far faster than trying to untangle all the metadata references.
    – sfdcfox
    Commented Jan 18, 2017 at 22:32
  • 3
    Oh god its like picking from two nightmares. A fun reminder of why SF devs are still in so much demand.
    – smohyee
    Commented Jan 18, 2017 at 22:34
  • 1
    @smohyee I've only ever had to do this about once. I hope I never have to do it again.
    – sfdcfox
    Commented Jan 18, 2017 at 22:38

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .