How to Fix Leads Matched to the Wrong Salesforce Account
Trace the evidence chain, mark manual_hold to freeze the row, fix the root signal, and re-evaluate. No hidden score to argue with — every decision code names its own cause.
Published April 18, 2026 • Gremlin Salesforce L2A is currently in private beta
Short answer
Run g-gremlin salesforce l2a trace --email <email> to surface the evidence chain. Mark the lead as manual_hold with lead.mark_manual_hold while you fix the root cause (known_account_map, hierarchy, inactive account, or incumbent value). Clear the hold and scout again to re-evaluate.
Diagnostic workflow
Five steps from symptom to verified fix.
Trace the lead
Run trace with --lead-id or --email. Gremlin returns normalized inputs, candidate account chain, evidence chain, and why the decision landed where it did.
Identify the conflicting signal
Usually one of: shared domain across accounts, a known_account_map entry that is out of date, a parent/child collision, or an incumbent field value overriding Gremlin.
Mark manual_hold
lead.mark_manual_hold sets Gremlin_Match_Status__c to manual_hold. Subsequent runs emit L2A_BLOCK_MANUAL_HOLD and will not re-evaluate the row until the hold is cleared.
Fix the root signal
Update the known_account_map, resolve the parent/child hierarchy, retire an inactive account, or clear the stale incumbent value. The fingerprint changes, invalidating SKIP_NO_RELEVANT_CHANGE.
Re-evaluate and verify
Scout again, trace the lead to confirm the new decision code, and clear manual_hold. Apply the new decision through the standard plan-hash path.
Trace the lead
Returns the evidence chain, candidate accounts, decision code, and any downstream risk for the configured write field.
g-gremlin salesforce l2a trace \
--config ./gremlin.l2a.yaml \
--email [email protected]Sample trace output
lead_id: 00Q5g000012345EAA
decision_code: L2A_REVIEW_DOMAIN_MULTI_ACCOUNT
candidate_accounts:
- 001xx000003ABC1 Acme Holdings (parent, band=high)
- 001xx000003ABC2 Acme North America (child, band=high)
evidence: normalized_domain=acme.com; 2 accounts share domain
existing_field: Account_Match__c = 001xx000003ABC1 (disagreement)
risk: Account_Match__c feeds assignment rule "L2A Route"
planned_action: none (review required)Common causes and fixes
Most wrong-match symptoms trace back to one of these five root causes. The decision code names the cause directly.
| Cause | Decision code | Fix |
|---|---|---|
| Shared email domain across multiple active accounts | L2A_REVIEW_DOMAIN_MULTI_ACCOUNT | Review queue — operator picks the correct account or escalates to parent/child logic |
| Known_account_map entry points at a legacy account | L2A_SAFE_KNOWN_ACCOUNT_MAP_SINGLE_ACCOUNT (wrong) | Update the map entry; re-run scout to invalidate the fingerprint cache |
| Parent account picked when a child should own the lead | L2A_REVIEW_PARENT_CHILD_COLLISION | Route to the parent/child collision page for hierarchy-aware resolution |
| Incumbent field value disagrees with the deterministic decision | L2A_REVIEW_EXISTING_NON_GREMLIN_VALUE | Trace both candidates, escalate to RevOps, and decide which source wins |
| Consumer email domain bridged to an account by a heuristic tool | L2A_REVIEW_CONSUMER_EMAIL_ONLY | Consumer domains do not auto-match in Gremlin — clear the wrong value and route to review |
Don't overwrite incumbent values to force a fix
If the wrong value lives in a customer-owned field that feeds assignment rules, overwriting it can fire routing. The correct path is to mark manual_hold, resolve the root cause (often upstream of Gremlin), and either clear the incumbent value deliberately or switch to gremlin_owned writes for new signals.
The downstream automation risk audit page covers how to classify the field and what --ack-risk-audit is for.
FAQ
Why are leads in Salesforce matching to the wrong account?
Four root causes account for most wrong matches: two or more active accounts share the lead's email domain, a known-account override points at a legacy account, the incumbent matcher auto-resolved a parent/child collision, or an inactive account is still being counted as a candidate. Trace the specific lead to see which one — the decision code names the cause directly rather than hiding behind a similarity score.
How do I diagnose a lead matched to the wrong account?
Run g-gremlin salesforce l2a trace --email <email> or --lead-id <id>. Gremlin returns the normalized inputs, the candidate account chain considered, the evidence chain, the decision code, and any existing-field comparison. The output answers "why did this lead land here" without a hidden score to argue with.
What is manual_hold and when should I use it?
manual_hold is a Gremlin-owned state that pauses re-evaluation for a lead. The safe action lead.mark_manual_hold sets Gremlin_Match_Status__c to manual_hold. Subsequent scout runs emit L2A_BLOCK_MANUAL_HOLD and skip the row. Use it while fixing the root cause so the row does not flap back.
How do I clear a manual_hold?
Update the state field or flip the review flag. Once cleared, the next scout run re-evaluates normally. The fingerprint is recomputed from current lead and account state, so any upstream fixes take effect immediately.
Can Gremlin overwrite an incumbent wrong value?
Not by default. Under shared_existing, overwrite_mode defaults to if_empty_only, so a populated value yields L2A_BLOCK_SHARED_FIELD_NONEMPTY. Clear the incumbent value manually or in a one-off script, then run scout and apply. Under gremlin_owned, the Gremlin namespace fields are the source of truth and the incumbent value is untouched.
What if the wrong match was set by a different tool?
Route to the downstream automation risk audit first. The wrong match may be coming from an assignment rule, Flow, or incumbent L2A tool that writes the match field. Observe_existing surfaces the disagreement; fixing it at the source is the durable path.
Keep the conversation going
These pages are meant to help operators solve real problems. If you want the next guide, grab the low-friction option. If you need the implementation, not just the guide, book time.
Get the next guide when it ships
I publish architecture guides grounded in real implementations. No generic AI filler.
Use your work email so I can keep the list useful and relevant.
Need the implementation, not just the guide?
Book a 15-minute working session with Mike right on his calendar. Tooling, consulting, or a mix of both is fine.
Open Mike's calendarIf you want me to come in with context, leave your email and a short note before the call.