Salesforce deploy and retrieve errors — CLI messages, source-format errors, server component failures, coverage, quick deploy, and Agentforce-specific deploy failures
What a failed Salesforce deploy or retrieve means and how to fix it — the CLI's own messages (conflicts, nothing to deploy, timeouts, invalid or expired deploy IDs), source-format errors (could not infer type, no source-backed components, forceignored meta files), server failures (Not available for deploy for this organization, missing referenced fields, invalid cross reference id, 75% coverage) and Agentforce deploy failures.
markdownreferencev1H04H-1PAMstage: deploytrust: officialservice: dxinterface: cliWe couldn't complete the operation due to conflictsThere are changes in the org that conflict with the local changesNo local changes to deployThe command has timed outalthough the deployment is still runningInvalid deploy IDJob ID can't be used for quick deploymentYou must specify tests using the --tests flagCould not infer a metadata typeNo source-backed components present in the packageNo components in the package to retrieveis forceignored but is required fordoes not have an associated metadata xml to parseUnexpected child metadataTestLevel cannot beNot available for deploy for this organizationIn field - no CustomField named foundinvalid cross reference idAverage test coverage across all Apex Classes and Triggers isat least 75% test coverage is requiredThis feature is not currently enabled for this user type or orgmissing required metadata Bot BotVersion AiAuthoringBundleSalesforce Integration license can't deploy metadata
Deploy and retrieve errors
Where to look: the CLI prints component failures with type, name, line and problem. --json gives the same detail for scripts, and sf project deploy report --job-id <id> re-reads a finished job.
CLI messages
| Message | Cause → fix |
|---|---|
| "There are changes in the org that conflict with the local changes you're trying to deploy." | Source tracking found someone changed the same components in the org. Keep yours with --ignore-conflicts, or take theirs with sf project retrieve start --ignore-conflicts |
| "No local changes to deploy." | Tracking sees nothing new. Check with sf project deploy preview, or deploy explicitly with --source-dir |
| "The command has timed out, although the deployment is still running." | --wait elapsed: sf project deploy resume |
| "Invalid deploy ID: … for org: …" | Wrong job ID or wrong --target-org |
| "Job ID can't be used for quick deployment. Possible reasons include the deployment hasn't been validated, has already been deployed, or the validation expired because you ran it more than 10 days ago." | Validate again (reference/dx/deploy-retrieve-and-tests.md) |
| "You must specify tests using the --tests flag if the --test-level flag is set to RunSpecifiedTests." | Add --tests |
| "TestLevel cannot be '…' unless API version is … or later" | Raise --api-version, or use another test level |
Source-format errors (before anything reaches the org)
| Message | Cause → fix |
|---|---|
| "…: Could not infer a metadata type" | The file isn't in a known folder with a known suffix (reference/dx/projects-and-source-format.md). Move or rename it |
| "No source-backed components present in the package." | The paths or manifest matched nothing deployable, often because everything is forceignored |
| "Metadata xml file … is forceignored but is required for …" | .forceignore hides a -meta.xml a component needs |
| "SourceComponent … does not have an associated metadata xml to parse" / "…: Expected source files for type '…'" | A half-copied component: add the missing -meta.xml or content file |
| "Unexpected child metadata [...] found for parent type [...]" | A child file sits under the wrong parent folder |
Server component failures
| Message | Cause → fix |
|---|---|
| "Not available for deploy for this organization" | The feature isn't enabled in the target org, the deploying user lacks the permission (an API-only Salesforce Integration licence generally can't deploy flows, permissions or Apex), or the orgs' API versions differ |
| "In field: field - no CustomField named … found" | A profile or permission set references a field that doesn't exist in the target yet. Deploy the field first, then the profile or permission set, or include both |
| "invalid cross reference id" | A component points at another one that the deploy creates later or doesn't include, such as an app's profile overrides. Include or create the dependency first |
| "Average test coverage across all Apex Classes and Triggers is 65%, at least 75% test coverage is required." | Production coverage rule: add tests, or use RunSpecifiedTests with tests covering each class and trigger in the package |
Agentforce deploys
| Symptom | Cause → fix |
|---|---|
| "This feature is not currently enabled for this user type or org" | Einstein and Agentforce aren't on. Turn them on in Setup; for scratch orgs, add the features to the definition (reference/orgs/orgs-and-editions.md) |
Errors about missing Bot or BotVersion | A committed Agent Script agent needs its AiAuthoringBundle and its Bot / BotVersion: deploy them from one manifest |
| Agent behaves as before after a publish | Publishing an authoring bundle doesn't deploy Apex or flows: deploy the actions first |
More agent validate, preview, publish and activate failures: reference/agentforce/agent-errors.md.