Deployment Component Failure

What does this error mean?

When Salesforce deploys a set of metadata changes, every component in the deployment package must pass validation before any change is written to the target org. This is an all-or-nothing transaction — if a single Apex class, trigger, Lightning component, Flow, or custom object fails, the entire deployment is rejected and rolled back.

The error message itself is a container: the real information is in the per-component error detail, accessible in Setup → Deployment Status or in your CLI output. Always read the component-level errors, not just the top-level failure message.

Common Causes

1. Apex compilation errors

An Apex class or trigger in the deployment contains a syntax error, references a method or field that doesn't exist in the target org, or depends on another class that failed compilation. The target org compiles all Apex fresh on each deployment — a class that compiled fine in sandbox may fail if the target org is on a different API version or is missing a dependency.

2. Test class failures or insufficient coverage

Production deployments require at least 75% overall Apex code coverage and all test methods must pass. A test that relied on sandbox-specific data or configuration will fail in production. Tests that call external callouts without proper mocking will also fail.

3. Missing dependencies in the target org

A component references a custom field, object, permission set, named credential, or another metadata type that exists in your source org but hasn't been deployed to the target yet. Salesforce validates all references at deploy time. Deploy dependencies in the correct order, or include them in the same deployment package.

4. Managed package API name conflicts

If the target org has a managed package installed with a component that shares an API name with something in your package, the deployment will fail with a duplicate or conflict error. Namespace prefixes must be unique.

5. Invalid metadata for the target API version

Deploying metadata built against a newer API version than the target org supports, or using features (e.g., new Flow element types) not available in the target org's Salesforce release, causes component-level validation failures.

How to Fix It

Solution 1: Read the component-level error detail

The top-level "Deployment Component Failure" message is not the fix — the per-component error is. Navigate to the deployment detail view or read your CLI output carefully.

Setup → Environments → Deploy → Deployment Status
  → Click "View Details" on the failed deployment
  → Expand each failing component to see the exact error message

Solution 2: Validate before you deploy

Run a check-only (validation) deployment first. This runs all the same validation steps as a real deployment — including test execution — but writes nothing to the org. Fix all errors, then deploy.

# Validate only — no changes written to org
sf project deploy start --check-only --target-org myOrg

# With specific test level
sf project deploy start --check-only --target-org myOrg --test-level RunLocalTests

# Deploy for real once validation passes
sf project deploy start --target-org myOrg --test-level RunLocalTests

Solution 3: Run tests before deployment

Run all local tests in the target org before deploying to surface any test failures caused by existing org state, data configuration, or callout issues.

# Run all local tests in the target org
sf apex run test --target-org myOrg --test-level RunLocalTests --result-format human

# Run a specific test class
sf apex run test --target-org myOrg --class-names MyApexTest --result-format human

Solution 4: Fix callout mocking in test classes

Tests that make HTTP callouts without a mock will throw a System.CalloutException during deployment test runs. Implement HttpCalloutMock for any test that exercises callout code.

@isTest
global class MockHttpResponse implements HttpCalloutMock {
    global HTTPResponse respond(HTTPRequest req) {
        HttpResponse res = new HttpResponse();
        res.setStatusCode(200);
        res.setBody('{"status":"ok"}');
        return res;
    }
}

@isTest
private class MyCalloutServiceTest {
    @isTest
    static void testCallout() {
        Test.setMock(HttpCalloutMock.class, new MockHttpResponse());
        Test.startTest();
        MyCalloutService.callExternalApi();
        Test.stopTest();
        // assert expected results
    }
}

Solution 5: Deploy missing dependencies first

If the error references a field, object, or metadata component that doesn't exist in the target org, deploy the dependency in a separate package first, then redeploy the original package.

# Deploy the dependency package first
sf project deploy start --source-dir force-app/main/default/objects --target-org myOrg

# Then deploy the full package
sf project deploy start --target-org myOrg