I've found a bunch of resources on how to setup and deploy/retrieve data to Salesforce Dx Scratch Orgs but only for extremely simple code bases.

Ideally, what I'd like to be able to do with Salesforce Dx is:

  1. Retreive all metadata (code and config) from my Production Org (all unmanaged package code/config).
  2. Create a new Salesforce Dx project and convert the Production Metadata to Dx project structure.
  3. Push the source to git.
  4. Push the newly converted production metadata to a scratch org.
  5. For each branch in git, do #3 and #4 to easily migrate branch code for testing to a scratch org.

My production code has a complex data model with over 4 dozen custom objects and complex code dependencies between apex classes, visual force pages, components, etc. For the life of me, I'm unable to get these code to push without encountering 1000s of errors.

My Questions are:

  • Has anyone had success using this process to migrate complex production metadata to a scratch org?
  • Winter 18' has a pilot for migrating production shape to scratch orgs. There isn't much documentation on this. Will this essentially copy all custom metadata to a scratch org?

3 Answers 3


There are different types of hurdles you will need to overcome to deploy to a scratch org. The same issues apply if you're trying to deploy to a developer org (not developer sandbox), but scratch orgs allow you to overcome some of them.

From easiest to hardest:

  1. Org Edition and Features
  2. Org Settings
  3. Org-Specific Metadata
  4. Org-Specific Limits
  5. Known Issues

Org Edition/Features

Some metadata can only be deployed to orgs with specific features enabled. For example, the CurrencyIsoCode fields can only be deployed if the MultiCurrency feature is enabled during scratch org creation.

You need to identify which features to enable in your scratch org definition file.

Org Settings

Some metadata can only be deployed to orgs when other metadata has specific values. For example, Case.SourceId can only be deployed if the IsLiveAgentEnabled setting is enabled.

These settings are stored as metadata so you can store them under version control. You can also deploy them to an org so you can adjust them while troubleshooting deployment errors. (Although some settings can't be changed through the metadata API, or can't be disabled once enabled.)

sfdx force:org:create supports setting some of the org settings so you can update your scratch org definition file once you figure out which settings you need enabled.

Org-Specific Metadata

Some metadata can be tied to data in an org. You'll want to try to break these dependencies by updating your metadata.

For example, Workflow alerts can reference Users. Since these Users won't exist in the scratch org, you will probably want to update these to use Groups or Roles, which are stored as metadata, instead.

Custom Org Limits

You might have non-standard limits available in your production org such as an increased number of Sharing Rules allowed. This will have to be addressed through the new Org Shape functionality.

Known Issues and Bugs

There's at least one known issue related to history tracking that will might prevent deploying the metadata from a large production org to a scratch org for the time being.

If you run into other errors, check the known issues and report them.


I'm the Product Manager running the pilot for creating scratch orgs with production org shape. Production shape implies all the limits, licenses and preferences that you may have in the production org which you're not aware of but would like to easily replicate in a scratch org. The feature does not copy over custom metadata from the production org. Our vision with DX is to drive development from source which means you have to externalize metadata to a version control system. If you'd like to try the pilot, please sign up on the link below and I'll set you up with a trial org to try it out. https://docs.google.com/forms/d/e/1FAIpQLSeX7nwJOc22UukRUALj4_ivVCuWPjKPGn9Zukm5oVL57QOExw/viewform

Also, please join the Salesforce DX Trailblazer community where the rest of the DX team can help you with the source push errors. https://success.salesforce.com/_ui/core/chatter/groups/GroupProfilePage?g=0F93A000000HTp1SAG

  • 8
    I agree that metadata should be part of the source & not part of the org, but this seems to overlook the real issue with the question. The asker is having difficulty importing their metadata into the scratch org, something myself and a lot of other people who have tried to use this tool have experienced. When you're writing an app from scratch, sfdx makes a lot of sense. When you're working with metadata that's years old, with subtle customizations which your tests may depend on, it becomes much more difficult to use these tools. Commented Nov 28, 2017 at 14:35
  • 2
    A realistic solution probably wouldn't be using org shape to create picture perfect scratch orgs (those are basically sandboxes), but an improvement on the metadata export tools available to create source metadata which can be easily used with scratch orgs. Commented Nov 28, 2017 at 14:37
  • 4
    @battery.cord is correct. This is pretty silly that we cannot get even basic meta data into scratch orgs or even pushed to sandboxes through the CLI. I have been fighting this for two days at this point. Here is an example: I just want to get the record types and certain fields from production so I can code around them. Using DX seems to mean that I have to completely rebuild the metadata for a scratch org, which will expire in a couple weeks. That seems pointless, and makes DX seem completely pointless to "admin-elopers"
    – Chance
    Commented Feb 13, 2018 at 16:34

Here is the line from the documentation that was shared in the Pilot group

"....But you do know one thing—you need to develop and test new features and functionality using an environment that mimics the features, limits, and preferences of your production org without the extraneous data and metadata"

From this statement, it can be understood that the Org Shape feature will not copy metadata to the scratch org.

Since this feature is not yet GA, it might change in future. But this is what it is at this moment.

You must log in to answer this question.

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