BadElement / Element type required / package.xml is malformed

Salesforce deploys are driven by an XML manifest (package.xml) that lists the metadata types and members to ship. The platform parses the manifest before doing anything else. Malformed XML, unknown types, or version mismatches stop the deploy here.

A valid package.xml looks like this

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>AccountTriggerHandler</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>Account.Region__c</members>
        <name>CustomField</name>
    </types>
    <version>60.0</version>
</Package>

Each <types> block has one <name> (the metadata type) and one or more <members> (the API names of components). The <version> declares the metadata API version.

Common mistakes

1. Wrong type name

<types>
    <members>MyClass</members>
    <name>ApexClasses</name>   <!-- ❌ "ApexClasses" — should be "ApexClass" -->
</types>

Type names are singular: ApexClass, CustomField, LightningComponentBundle, Flow. The full list is in the Metadata API docs.

2. Wildcard misuse

<types>
    <members>*</members>
    <name>ApexClass</name>   <!-- All classes — works -->
</types>

Wildcards are valid for many metadata types, but not for all. Things like Workflow, CustomField, and Layout may need explicit member names.

3. Component-name format wrong

<types>
    <members>Region__c</members>            <!-- ❌ field needs object qualifier -->
    <name>CustomField</name>
</types>

Most members for sub-components use <Object>.<API_Name> format:

<members>Account.Region__c</members>      <!-- ✅ -->

The same applies to validation rules (Account.MyValidationRule), record types (Account.Customer), etc.

4. API version mismatch

The <version> element must match a supported API version. As of late 2026, valid versions are roughly 30.0–62.0. Beyond that, the platform may reject:

<version>99.0</version>   <!-- ❌ unsupported -->

Stick to the version your sf CLI / SDK is built against. Newer features need newer versions, but don't pre-declare a version that doesn't yet exist.

5. Stray XML

<types>
    <members>MyClass</members>
    <name>ApexClass</name>
</types>
<my-custom-element>foo</my-custom-element>   <!-- ❌ unknown element -->

Even one unknown XML element makes the whole manifest invalid.

Validate locally before deploying

The CLI has a manifest validator:

sf project deploy validate --manifest package.xml --target-org production

Or use a simple XML linter (xmllint --noout package.xml) to catch syntax errors. For deeper checks, generate the manifest with sf project generate manifest instead of hand-writing it — the CLI's output is always well-formed.

A subtler source: build pipelines that mangle XML

CI scripts that sed the manifest to bump version numbers sometimes corrupt the XML (escape characters, missing closing tags). If your manifest works locally but fails in CI, your pipeline's XML manipulation is suspect. Replace sed with a real XML tool like xmlstarlet.