sf project retrieve start fails with "Entity expansion limit exceeded: 1118 > 1000" (MetadataTransferError) on every retrieve request

[Alfystar]

Summary

We are consistently unable to retrieve metadata using sf project retrieve start. Every retrieve attempt fails with:

Error (MetadataTransferError): Metadata API request failed: Component conversion failed: Entity expansion limit exceeded: 1118 > 1000

This happens for every retrieve request, across retries, and we cannot determine what triggers the “entity expansion” limit or how to avoid it.

---

Steps To Reproduce

IMPORTANT
We cannot provide a public repository or org access because the project and metadata are under NDA / internal constraints. However, the issue is reproducible in our environment with the steps below and happens systematically.

1. Prepare a Salesforce DX project (standard sf project).
2. Create a package.xml (or manifest) that retrieves metadata containing at least one CustomObject (in our case, it happens even when the manifest targets a single batch/package).
3. Run the retrieve command:

sf project retrieve start \
  --target-org RM_PROD \
  --ignore-conflicts \
  --manifest fullRetrieve_Artifact/package_CustomObject_1.xml \
  --output-dir fullRetrieve_Artifact/retrievePack/dir_051_01 \
  --wait 20

4. Observe that the retrieve request is created and progresses to “In Progress”, then fails with the error below.
5. Retrying the same command (immediately or later) results in the same error.

---

Expected result

The retrieve should complete successfully and download the metadata specified in the manifest into the provided --output-dir.

---

Actual result

The retrieve fails consistently with a MetadataTransferError:

───── Retrieving Metadata ─────
Stages:
1. Preparing retrieve request
2. Sending request to org
3. Waiting for the org to respond
4. Done

▶ Sending request to org…
   Retrieving v64.0 metadata from <user> using the v62.0 SOAP API
✔ Sending request to org (...)
   Status: Pending

▶ Waiting for the org to respond…
   Status: In Progress
✘ Waiting for the org to respond (...)

STDERR:
Error (MetadataTransferError): Metadata API request failed: Component conversion failed:
Entity expansion limit exceeded: 1118 > 1000

Warning: org-api-version configuration overridden at 62.0

Additional observation:

• The CLI shows: “Retrieving v64.0 metadata … using the v62.0 SOAP API”
• The retrieve remains In Progress for a while and then fails.
• The failure is reproducible across multiple retries (we currently retry 3 times, always fails).

---

Additional information

• This issue occurs for every retrieve request we execute in our automation (CI pipeline) and not only for one specific component.
• It appears related to component conversion / entity expansion, but we do not know:
  • what entity is being expanded,
  • why it exceeds 1000,
  • or how to split/structure the retrieve to avoid this.
• If there is a known workaround (e.g., API version alignment, alternate retrieve mode, flags, or a recommendation for splitting manifests differently), guidance would be greatly appreciated.

• CLI version note: some teammates configured our pipelines to use @salesforce/cli 2.129.5. This looks unusual to us because we believe the latest stable release is 2.127.2. We are therefore unsure whether the issue could be related to using an unexpected/non-standard CLI version (or a version that may not be generally available), and we would appreciate confirmation on whether 2.129.5 is a valid published release and if it could affect metadata retrieve behavior.

---

System Information

{
  "architecture": "darwin-arm64",
  "cliVersion": "@salesforce/cli/2.127.2",
  "nodeVersion": "node-v25.8.1",
  "osVersion": "Darwin 25.3.0",
  "rootPath": "/opt/homebrew/lib/node_modules/@salesforce/cli",
  "shell": "zsh",
  "pluginVersions": [
    "@oclif/plugin-autocomplete 3.2.40 (core)",
    "@oclif/plugin-commands 4.1.40 (core)",
    "@oclif/plugin-help 6.2.37 (core)",
    "@oclif/plugin-not-found 3.2.74 (core)",
    "@oclif/plugin-plugins 5.4.56 (core)",
    "@oclif/plugin-search 1.2.38 (core)",
    "@oclif/plugin-update 4.7.19 (core)",
    "@oclif/plugin-version 2.2.36 (core)",
    "@oclif/plugin-warn-if-update-available 3.1.55 (core)",
    "@oclif/plugin-which 3.2.43 (core)",
    "@salesforce/cli 2.125.2 (core)",
    "agent 1.30.6 (core)",
    "apex 3.9.10 (core)",
    "api 1.3.10 (core)",
    "auth 4.1.6 (core)",
    "code-analyzer 5.10.2 (user) published 16 days ago (Mon Mar 09 2026) (latest is 5.11.0)",
    "data 4.0.73 (core)",
    "deploy-retrieve 3.24.11 (core)",
    "info 3.4.105 (core)",
    "limits 3.3.78 (core)",
    "marketplace 1.3.10 (core)",
    "org 5.9.69 (core)",
    "packaging 2.25.5 (core)",
    "schema 3.3.94 (core)",
    "settings 2.4.57 (core)",
    "sobject 1.4.84 (core)",
    "telemetry 3.8.0 (core)",
    "templates 56.9.3 (core)",
    "trust 3.7.114 (core)",
    "user 3.6.52 (core)",
    "apex-code-coverage-transformer 2.14.1 (user) published 148 days ago (Mon Oct 27 2025) (latest is 2.18.0)",
    "sfdx-plugin-source-read 1.5.6 (user) published 192 days ago (Sun Sep 14 2025)"
  ]
}

[github-actions]

Thank you for filing this issue. We appreciate your feedback and will review the issue as soon as possible. Remember, however, that GitHub isn't a mechanism for receiving support under any agreement or SLA. If you require immediate assistance, contact Salesforce Customer Support.

[Alfystar]

✅ Resolution

We have identified the root cause of the issue.

The problem was caused by using a non‑stable Salesforce CLI version (@salesforce/cli 2.129.5) configured in our environment. After re-running the same retrieve commands using the latest stable release (2.127.2), the metadata retrieval completed successfully without any errors.

It appears the issue was therefore related to the CLI version rather than to the Metadata API itself.

We sincerely apologize for the time spent investigating this and for any noise this issue may have caused. Thank you for your attention and for maintaining the CLI — we really appreciate your work.

Best regards,