jiten-singh-shahi/sf-build-fix

Build Fix — Salesforce Build and Deployment Error Resolution

Fix build and deployment errors incrementally. Parse error output, classify issues, fix one at a time, re-validate.

Reference: @../_reference/DEPLOYMENT_CHECKLIST.md

When to Use

• When Apex compilation errors are blocking a deployment
• When metadata conflicts prevent deploying to a target org
• When test failures need to be resolved before deployment validation passes
• When dependency resolution is needed (missing objects, fields, or class references)
• When you receive build errors from sf project deploy and need systematic resolution

Workflow

Step 1 — Capture Errors

Run a dry-run deployment or check compiler output:

sf project deploy validate --target-org <alias> --json 2>&1

If the user pasted error output directly, use that instead.

Step 2 — Parse and Classify

Group errors by type and fix in this dependency order:

| Priority | Error Type | Fix Strategy | |----------|-----------|--------------| | 1 | Missing object/field metadata | Deploy metadata first -- objects before classes | | 2 | Missing class/interface reference | Check spelling, verify class exists, check API version | | 3 | Type mismatch | Cast explicitly, check null handling, verify generic types | | 4 | Method signature changed | Update all callers, check for overloaded methods | | 5 | Metadata conflict | Retrieve latest from org with sf project retrieve start, merge | | 6 | Test failure | Fix test data setup, update assertions, check @TestSetup | | 7 | Governor limit in test | Add Test.startTest()/stopTest(), reduce data volume |

Step 3 — Fix One at a Time

For each error:

1. Read the file at the reported line number
2. Understand the context (class, method, trigger)
3. Apply the minimal fix
4. Verify it compiles: sf project deploy validate --metadata "ApexClass:<ClassName>" --target-org <org>

Step 4 — Re-validate

After all fixes:

sf project deploy validate --target-org <alias> --test-level RunLocalTests

Common Apex Compilation Errors

| Error Message Pattern | Root Cause | Fix | |----------------------|------------|-----| | Variable does not exist: X | Undeclared variable or field removed | Declare variable or check field API name | | Method does not exist or incorrect signature | Wrong parameter types or method renamed | Check method signature in target class | | Illegal assignment from X to Y | Type mismatch | Add explicit cast or fix generic type | | Non-void method might not return a value | Missing return in a branch | Add return statement to all code paths | | Compile Error: unexpected token | Syntax error | Check line above the reported line | | System.NullPointerException (test) | Null reference in test setup | Add null checks or fix @TestSetup | | Duplicate value found (test) | Test data collision | Use unique identifiers, avoid SeeAllData | | FIELD_CUSTOM_VALIDATION_EXCEPTION (test) | Validation rule blocking test DML | Populate all required fields in test data | | MIXED_DML_OPERATION (test) | Setup + non-setup DML in same transaction | Use System.runAs() in tests or @future in production | | UNABLE_TO_LOCK_ROW (test) | Concurrent test data conflicts | Use unique records per test method |

Dependency Resolution Order

When deploying multiple metadata types, follow this order:

1. Custom Objects and Fields
2. Record Types and Page Layouts
3. Apex Classes (utilities and base classes first)
4. Apex Triggers
5. Lightning Web Components
6. Flows (Process Builder is deprecated since Winter '23 -- migrate to Flows)
7. Permission Sets and Profiles
8. Apex Test Classes (verify at end)

Metadata Conflict Resolution

When sf project deploy reports conflicts:

1. Retrieve current org state: sf project retrieve start --metadata <type>:<name>
2. Compare: diff force-app/main/default/<path> <retrieved-path>
3. Merge: Keep production changes, layer your modifications on top
4. Do not force-overwrite production metadata without understanding the diff

Rules

• Fix one error at a time -- cascade fixes often resolve multiple issues
• Do NOT refactor while fixing builds
• Do NOT change architecture
• If a fix introduces new errors, revert and try a different approach

Examples

sf-build-fix
sf-build-fix Fix the Apex compile errors from this deployment output: <paste errors>
sf-build-fix The AccountService.cls has a type mismatch on line 47
sf-build-fix Resolve the metadata conflicts blocking our deployment to UAT

Related

• Constraints: sf-deployment-constraints -- deployment safety rules and validation gates