---
cuppy_hub: salesforce
cuppy_path: reference/dx/deploy-errors.md
cuppy_section: docs
cuppy_doc: H04H-1PAM
cuppy_doc_uuid: 3c2e9741-08ca-4bd0-8f72-6744b60aacf8
cuppy_permalink: https://cuppy.io/salesforce/d/H04H-1PAM
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/dx/deploy-errors
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: f485e88a820e4b63e2f84819edfa772dec57c3c5203859a6a0601261c1ed265c
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# 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`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->