Skip to content

Entity Resolution Troubleshooting

Common problems when creating and running an Entity Resolution check, their causes, and how to resolve them.

Validation Fails When Creating the Check

Clicking Validate returns an error instead of a success message.

Cause: The configuration was rejected, or the rule could not run against the selected data. The most common reasons are a distinction field of an unsupported type, a target field that does not exist on the container, the same field configured twice, a weight that is blank, negative, or zero on every Compare field, an invalid Filter Clause, or a container that failed to load.

Resolution:

  1. Review the error message: it explains what needs attention.
  2. Confirm the Distinction Field is a Date, Timestamp, Integral, Fractional, String, or Boolean field, and that every Block and Compare Field exists on the container and appears only once.
  3. Check the Weight on every Compare field: none can be blank or negative, and at least one must be above zero. The API page lists the full set of messages these rules produce.
  4. Check the Filter Clause for typos: it must be a valid SQL WHERE expression for the selected container.
  5. If the message says the container is marked as Unloadable, the container was skipped after repeated operation failures. Follow the steps in Unloadable Container Error.

Almost Every Record Ends Up in Its Own Cluster

The run produces nearly as many entities as records, and the operation logs point it out.

Cause: Records are not reaching the composite match threshold. Either the threshold is too high for how much the values vary, or the comparison types are too strict (exact comparisons where the data has real-world variation).

Resolution: Lower the threshold, add a fuzzy string comparison on the descriptive fields, and check the weights: a low-signal field carrying a high weight drags every score down. The operation logs flag runs where more than 90% of records stay in single-record clusters, which is the signal to re-tune.

Records That Are Clearly Different Land in the Same Cluster

Clusters merge entities that a human would never consider the same.

Cause: The threshold is too low for the discriminating power of the selected fields, or the comparison relies on fields that are nearly identical across the dataset.

Resolution: Raise the threshold, increase the weight of the fields that truly identify the entity, and consider promoting a genuine boundary (a country, a tenant) to a Block field so unrelated records never pair.

Records Are Skipped Instead of Reported

Rows you expected to see in a cluster never appear anywhere in the results.

Cause: A NULL in a block field. Records cannot be paired on a block field they do not have a value for, so they drop out of resolution silently.

Resolution: Pair the check with a Not Null check on the block fields so the omissions are reported, or move the field from Block to Compare so a missing value lowers the score instead of eliminating the pair.

Blocking Hides Legitimate Exceptions

Two records that should match never pair, even with a low threshold.

Cause: They disagree on a block field. Blocking is a hard gate applied before any scoring, so no amount of evidence from other fields can recover the pair.

Resolution: Move the field to the Compare role with an exact comparison and a high weight. The disagreement then reduces the score instead of eliminating the candidate pair.

The Check Did Not Evaluate at All

The scan finished but the check reported nothing, and the operation logs mention a limit.

Cause: Entity Resolution skips evaluation when the target fields produce more than five million distinct combinations. The safeguard prevents an unbounded comparison.

Resolution: Narrow the scope with a Filter Clause (one region, one segment, one period), or reduce the number of target fields so the combination space stays under the ceiling.

An Edited Check Keeps Behaving the Old Way

You changed the threshold or the fields but the anomaly list did not change.

Cause: Edits take effect on the next Scan. Saving the check does not re-cluster the data, and anomalies raised under the previous configuration are not modified.

Resolution: Run a Scan on the container (or wait for the scheduled one). Old anomalies stay open until you triage them or a Full scan with Auto Resolve clears them. See What Happens to Existing Anomalies.

Expected Per-Row Anomalies, Got a Single One

The check reports one anomaly instead of flagging each inconsistent record.

Cause: Entity Resolution is a Shape-only rule. The violation belongs to a cluster of records, not to one row, so it reports a single Shape Anomaly with the offending clusters attached.

Resolution: This is expected behavior. Open the anomaly's Source Records to see the non-compliant clusters, one example row per distinct distinction value, each carrying its cluster identifier.