I am trying to break up a large unlocked package (package A) by moving open source libraries to their own package (Package B). Package A has some custom code that references these libraries (FFLIB).

Salesforce documentation says in order to migrate Metadata from one package to another:

1). Identify the metadata to be moved from package A to package B.

2). Remove the metadata from package A, create a version, and release
the package.

3). Add the metadata to package B, create a version, and
release the package. 

4). In your production org, upgrade package A. In
your production org, install package B

Problem is on step 2 in creating version for package A, I get errors due to the custom code in package A having dependencies on FFLIB.

I can make package A dependent on package B but that would mean I would need to create a package B version first that has FFLIB in it. That seems to go against the documentation because that means I have 2 packages that have the same metadata (FFLIB) at one time installed.

How to proceed and what am I missing here?

  • If your package A is org-dependent. You shouldn't be getting errors in performing step 2. Because when you do step 2, fflib code will be still in the org but not part of any package and package A will compile successfully. I did the same scenario as yours in my org and it went smooth.
    – javanoob
    Commented Aug 19, 2021 at 22:34

1 Answer 1


Those instructions imply that you are going to move the dependent code out to a new package (i.e. your code will move, but the fflib code will remain where it is), rather than moving the dependency out of the package. If you don't want to do that, you'll have to follow these steps.

  • Create the new Package B, with its own directory
  • Move (not copy) fflib code to Package B
  • Create a new version of Package B
  • Update sfdx-project.json to add Package A's dependency on Package B
  • Create a new version of Package A
  • ⚠ Back up any data you might lose! ⚠
  • Uninstall Package A (⚠ ⚠ ⚠ may delete data! ⚠ ⚠ ⚠)
  • Install Package B
  • Install Package A

Note that the uninstall may delete data, so I'd recommend a backup of any data that might be involved by this process (your metadata will be fine after the process).

Unfortunately, there's no way around that step, because, as you've observed, you can't have the same metadata in two different packages at once, or installed at once.

If possible, consider migrating your code to a new package instead of trying to migrate fflib.

Also, notice above how we add a dependency and remove metadata in a single step. This is a perfectly legal upgrade option for a package. Unfortunately, you still can't upgrade A without installing B, and you can't install B without upgrading A. This Catch-22 is why you will need to uninstall A before you can install B.

  • Could the unpackagedmetadata setting in project json be used to build a package version if needed as an option? @sfdcfox Commented Aug 19, 2021 at 1:52
  • @jini I'm not sure. That might actually work in some scenarios. One would need to take care to only use that for one version, and only to upgrade orgs that need to cross that gap.
    – sfdcfox
    Commented Aug 19, 2021 at 12:20

You must log in to answer this question.

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