Fixing Entity Expansion Limit Exceeded in VS Code

If you work with large Salesforce orgs or complex metadata structures, you have probably had a retrieve fail in VS Code. The error Entity expansion limit exceeded: 1010 > 1000 shows up when the XML parser encounters a metadata file with too many entities defined.

The fix is part parser configuration and part discipline about how much metadata you pull at once.

Understanding the root cause

This is an XML security configuration limit, not a Salesforce governor limit. The Salesforce CLI, which powers the Salesforce Extension Pack for VS Code, uses standard XML parsers to process metadata files. Those parsers enforce a strict limit on entity expansion to prevent "XML External Entity" (XXE) attacks, a common vulnerability where attackers use specially crafted XML to exhaust server memory.

A retrieve pulls thousands of XML files. If any of them contain an excessive number of entity references (typically those starting with &), the parser hits its hard-coded safety threshold of 1000. In Salesforce orgs the culprit is usually complex Custom Labels, large Permission Sets, or a massive FlexiPage packed with dense, repetitive XML definitions.

Isolate the problematic metadata

Before you touch any settings, work out whether a specific file is corrupt or your project configuration is simply too broad.

1. Open the 'Output' panel in VS Code (Ctrl+Shift+U) and select 'Salesforce CLI' from the dropdown. The file path named right before the error appears is your first suspect.
2. Split the retrieval instead of pulling your entire package.xml. If you are pulling all custom objects, pull only a subset.
3. Once you have a suspect file (a massive Permissionset, say), open it in a text editor and look for repetitive blocks. This is rarely something anyone typed by hand; automated tools and older migrations sometimes inject redundant XML entities that trigger the threshold.

Modifying the environment variables

The direct way to address the Entity expansion limit exceeded error is to tell the Salesforce CLI process to allow a larger threshold. The CLI runs as a Node.js process, so you can pass environment flags that change how the underlying XML parser behaves.

The solution for Windows (PowerShell)

On Windows, raise the limit for one terminal session by setting an environment variable before you run your sfdx commands:

$env:NODE_OPTIONS = "--max-old-space-size=4096"
# Or specifically for entity expansion if using custom parsers
# Note: This is an OS-level override

The entity limit is often baked into the libxmljs or the specific XML engine used by the CLI, so this does not always help. If the error persists, the metadata bundle is what needs optimizing.

Optimizing your package.xml strategy

If you are hitting 1010+ entities, your package.xml is too heavy. Metadata retrieval is an expensive operation, and pulling the entire org into a single local project is a bad architectural practice.

A modular setup keeps each retrieve small:

• Break your project into smaller feature folders instead of one massive force-app.
• Use a .forceignore file so you aren't pulling back generated files that have nothing to do with your current development task.

Example of a clean .forceignore file:

# Ignore standard report types or generated docs
**/reports/**
**/dashboards/**
# Ignore specifically large, problematic objects
**/objects/Legacy_Massive_Object__c.object-meta.xml

Ignoring files that hit the parser limit but are not required for your current feature bypasses the error entirely.

When to contact Salesforce Support

If you have narrowed the error down to a standard metadata type you cannot ignore, such as a Profile or PermissionSet that is natively large, you may be hitting a structural issue with your org's metadata.

If the error shows up even on a narrow retrieve of a single file, check whether that file was corrupted during a deployment. Circular entity references can send the parser spiralling. If the XML appears valid and still triggers the error, send the file content to Salesforce Support, since the metadata encoding in your sandbox may be the problem.