Upcoming Behavior Change of `project deploy|retrieve start` (December 2025)

[jshackell-sfdc]

Starting in December 2025, the project deploy start and project retrieve start commands will require that the target org use source tracking, unless you specify the metadata you want to deploy or retrieve. If you deploy or retrieve to an org that doesn’t use source tracking, then you must specify the metadata you want to deploy or retrieve.

Orgs that don’t use source tracking include production orgs, Partial Copy sandboxes, Full sandboxes, and scratch orgs that were created with the --no-track-source flag.

Let’s drill down a bit. The following examples all use project deploy start, but the same applies to project retrieve start.

Current Behavior

Let’s say you create a scratch org with the --no-track-source flag, which means that it doesn’t use source tracking, and you give it the alias my-scratch. The following command currently appears to succeed:

sf project deploy start --target-org my-scratch

As of release 2.104.6 (Sept 3), the command will return a warning about the upcoming change in behavior but the deploy will still appear to succeed. However, the command doesn’t actually deploy anything and the internal state of your metadata could be incorrect.

This same behavior applies to other orgs that don’t use source tracking, such as production orgs.

Behavior Starting December 2025

When you run this command on a non-source-tracking org, you will get an error:

sf project deploy start --target-org my-scratch

You can still deploy to a non-source-tracking org, but you must use one of these flags to specify the exact metadata you want to deploy: --metadata, --source-dir, or --manifest. For example:

sf project deploy start --source-dir force-app --target-org my-prod-org

Why Are We Making This Change?

The correct behavior when deploying to (or retrieving from) an org that doesn’t use source tracking, and not explicitly specifying the metadata, is to fail. We introduced the incorrect behavior in a previous release, so now we are fixing the issue but giving you plenty of time to adjust to the change.

[daveespo]

@iowillhoit @cristiand391 -- was this change fully thought through from an efficiency perspective? We introduced the --no-track-source flag into our continuous integration pipeline two years ago and it provided a 10-25% improvement in deployment speed, depending on how you measure and what mood Salesforce is in when you take the measurements (i.e. the improvement in deployment is highly variable). We have roughly 2500 metadata components in our largest package.

We don't think that switching to a explicit set of metadata directories for deployment is the right choice -- it means our engineering team would be doing their local development by relying on what's defined in sfdx-project.json and the CI deployment would have to do its best to mimic that deployment logic and not diverge over time.

Seems like a lousy choice to have to make.

[github-actions[bot]]

Hello @jshackell-sfdc :wave: It looks like you didn't include the full Salesforce CLI version information in your issue. Please provide the output of version --verbose --json for the CLI you're using (sf or sfdx).

A few more things to check:

• Make sure you've provided detailed steps to reproduce your issue.
  • A repository that clearly demonstrates the bug is ideal.
• Make sure you've installed the latest version of Salesforce CLI. (docs)
  • Better yet, try the rc or nightly versions. (docs)
• Try running the doctor command to diagnose common issues.
• Search GitHub for existing related issues.

Thank you!

[FabienTaillon]

I don't know what was already started regarding this, but I'm not able anymore to deploy anything in VS Code, right clicking on a metadata and selecting SFDX: Deploy This Source to Org because the org doesn't have source tracking enabled:

17:27:01.417 Starting SFDX: Deploy This Source to Org

=== Deployed Source
No results found

This org does not have source tracking.

I'm using the lastest version of everything (including VS Code and VS Code extensions), here are the CLI version numbers:

sf plugins --core                                             
@oclif/plugin-autocomplete 3.2.34 (core)
@oclif/plugin-commands 4.1.32 (core)
@oclif/plugin-help 6.2.32 (core)
@oclif/plugin-not-found 3.2.65 (core)
@oclif/plugin-plugins 5.4.46 (core)
@oclif/plugin-search 1.2.28 (core)
@oclif/plugin-update 4.7.4 (core)
@oclif/plugin-version 2.2.32 (core)
@oclif/plugin-warn-if-update-available 3.1.46 (core)
@oclif/plugin-which 3.2.39 (core)
@salesforce/analytics 1.4.47
@salesforce/sfdx-scanner 4.12.0
agent 1.24.4 (core)
apex 3.6.19 (core)
api 1.3.3 (core)
auth 3.9.0 (core)
community 3.3.36 (3.3.36)
data 4.0.53 (core)
demo-plugin 1.0.0 (link) /Users/fabientaillon/Documents/tmp/demo-plugin
deploy-retrieve 3.22.41 (core)
dev 2.5.1 (2.5.1)
info 3.4.81 (core)
lightning-dev 4.4.13 (prerelease)
lightning-flow-scanner 3.29.0
limits 3.3.64 (core)
marketplace 1.3.8
org 5.9.23 (core)
packaging 2.19.5 (core)
schema 3.3.78 (core)
settings 2.4.42 (core)
sfdmu 4.38.0
sfdx-hardis 6.1.4
sfdx-plugin-source-read 1.5.4
signups 2.6.42 (2.6.42)
sobject 1.4.68 (core)
telemetry 3.6.55 (core)
templates 56.3.60 (core)
texei-sfdx-plugin 2.8.3
trust 3.7.113 (core)
user 3.6.34 (core)

[FabienTaillon]

Also, sf project deploy start ends up with No changes to deploy, while sf project deploy start -m LightningComponentBundle does work.

[SanjinPrelicEcho]

@FabienTaillon Downgrading the Salesforce CLI Integration VSC Extension resolves this issue.

[cristiand391]

hey all, sorry for the late reply.

Regarding broken deployments from vscode extensions: this an extension bug that just happened to happen around the same time this issue was published but it's unrelated to planned changes by the CLI team, see: https://github.com/forcedotcom/salesforcedx-vscode/issues/6505.

First I want to apologize since I was supposed to review the announcement but didn't get to it in time.

The current behavior for deploy/retrieve is:

sf project retrieve start

if no retrieve target is specified (--source-dir, --manifest, --metadata, --target-metadata-dir, or --package-name) and the org is tracking source, it will use source-tracking info to determine which changes to retrieve. If the retrieve target is set, it uses that to calculate what metadata to retrieve.

The org is tracking source bit specifically means the org auth file has the tracksSource field set to true (or if it's not set and is a scratch/sandbox org we set it to true). This tracksSource field is set to true when:

1. sf org create scratch/sandbox: pass the --no-track-source flag
2. force an org to track source via sf org enable tracking

If an org isn't tracking source and the user doesn't specify a retrieve target, the expected behavior is that the command throws this error:

Unable to track changes in your source files.
This command expects the org to support source tracking. If it doesn't, you must specify the metadata you want to retrieve.

but due to a wrong method I used for this check back then it just continues the retrieve with source-tracking info: https://github.com/salesforcecli/plugin-deploy-retrieve/pull/882/files the supportsSourceTracking method doesn't check the tracksSource, it always returns true for scratch orgs and if the orgs supports SourceMember object.

❗: the planned breaking change is to fix this by making project retrieve start fail if no retrieve targets were specified and the org doesn't track source. This is already the case for prod orgs so the only affected scenarios would be if you ran sf project retrieve start on scratch/sandboxes with source-tracking disabled as mentioned above.

sf project deploy start

if --metadata-dir isn't specified and the org is tracking source, it will use source-tracking info to calculate what changes to deploy.

When we talked about this change I mentioned some SourceMember records were being updated but I think I was wrong here (tracking library isn't creating any, just reading records and updating the local shadow git repo to keep stuff in sync).

We introduced the --no-track-source flag into our continuous integration pipeline two years ago and it provided a 10-25% improvement in deployment speed

@daveespo right, going through old discussions the decision made was that to enable/disable source-tracking for a scratch/sandbox the user should use --no-track-source and we specifically didn't add --tracks-source to deploy/retrieve to avoid people messing up the source-tracking syncing.

Since sf project deploy start on an org created with --no-track-source doesn't affect remote SourceMembers records and only relies on the local shadow git repo (which isn't sync'd to remote, that's where the perf gain is noticeable) I think we can back track and keep this behavior, I'll let you all know we discuss it with the team.

[burgarna]

https://salesforce.stackexchange.com/questions/434056/salesforce-cli-not-working-not-able-to-retrieve-files-to-the-vs-code

This issue started after the recent update. To fix it:

Open VS Code Settings. Search for salesforcedx-vscode-core.experimental: source tracking. Uncheck/disable that option. Press Ctrl+Shift+P, type Reload Window, and run it. After reloading, the error is resolved and retrieve works as expected.

[cristiand391]

@burgarna the extensions team posted workaround and will fix the issue in their next release: https://github.com/forcedotcom/salesforcedx-vscode/issues/6520

[vc4u]

What would happen to deploying/retrieving changes or working with Developer Edition orgs? Would deploying files from VS Code using context menu continue to work as-is? (I'm assuming that command actually deploys files with '--metadata' argument always.)

[De-L3ns]

We currently deploy to our FULL / PRD orgs by creating a package.xml to pass in the parameter of the sf project deploy start command. We assume this also follows the principle of specyfing the exact metadata that we want to deploy. Is this correct? We also provide the target org through --target-org.