Data Reconciliation Recipe Troubleshooting

This page documents the known problems while running the Data Reconciliation recipe and the steps to resolve them. Each section describes a symptom, its cause, and the resolution.

Selecting and Configuring

The Assets Have No Fields in Common

After picking both assets, the Schema overlap panel shows No fields in common and Next stays disabled.

Cause: Reconciliation pairs fields by name and type, and no field name appears on both assets, or every shared name has incompatible types on the two sides.

Resolution: Build a Computed Table on one side that renames or casts the columns to match the other, then select it in the recipe. Fields that share a name but not a type are listed in the panel with both types.

No Shared Field Qualifies as a Row Identifier

The Row Identifiers step reads "No shared field qualifies as a row identifier. Identifiers need 100% completeness; string fields must also be fully unique."

Cause: A row identifier must be complete on the left asset, and a text identifier must also be fully unique, as measured by the asset's profile. No shared, type-compatible field meets that bar.

Resolution: Profile the left asset again if the profile is stale. Otherwise add a reliable key to both assets, for example through a Computed Table, and select it.

An AI Suggestion Could Not Load

The footer shows that the AI row identifier suggestion, compare column suggestion, or scan analysis could not load.

Cause: The AI request failed. The usual reasons are that the AgentQ data sharing level is below Metadata Shared, that the AI provider did not answer in time or returned a response Qualytics could not use, or that one of the assets has no profiled fields.

Resolution: Click Run again on the banner or Retry on the alert. If it fails again, continue manually; every step works without AI. Ask your administrator to check the AgentQ data sharing level and the AI integration. See AgentQ Access Controls.

Review Reports a Conflict with an Existing Check

The Review step shows Conflict with an existing check: "An active data diff check already covers these fields on this table. Load it into the recipe, or change the configuration." Next is unavailable.

Cause: An active Data Diff check on the left asset already compares the same fields with the same filter, which the platform treats as a conflict.

Resolution: Click Load existing check to continue from the existing check's configuration, which discards the settings you were building. Or change the compare fields so the two checks no longer overlap, or archive the existing check from the datastore page first.

Validating and Scanning

Validate Fails

Clicking Validate shows Validation failed with a Retry action.

Cause: Saving or activating the check was refused. Activation needs the Author team permission on the left datastore, and the reference asset must be readable with at least Reporter on the right datastore. A refusal naming another check means the configuration conflicts with an active check and is handled on Review.

Resolution: Confirm your team permissions on both datastores and click Retry. For a conflict, follow the banner back to Review.

The Scan Step Asks to Link an Enrichment Destination

Scan shows Choose a datastore to receive the mismatched rows and a Link Enrichment button instead of Scan.

Cause: The left datastore has no linked enrichment destination. The scan writes every mismatched row there, with both sides' values, and the keep and remove sets are written there too.

Resolution: Click Link Enrichment and complete the dialog. The step unblocks as soon as the link is saved. See Link an Enrichment Destination from the Scan Step.

The Scan or the Materialize Fails Right Away

The step shows an error with a Retry Scan or Retry action as soon as you click Scan or Materialize.

Cause: Either you lack the Editor team permission on the left datastore, which running operations requires, or, for the materialize, the enrichment destination is disconnected or its link was removed after the scan. A materialize can also fail when one of the two assets is too large for your deployment to load as one piece, or when the reference asset holds no data; the operation's message says which.

Resolution: Confirm your team permission on the datastore. Test the enrichment datastore's connection from its page, then click Retry. For an asset that is too large, narrow it with a filter on the check or a Computed Table, or contact your administrator.

Mismatch Records Are Not Loaded

The Scan step shows Mismatch records not yet loaded, or the Reconcile step says the scan found mismatches but their records are not loaded.

Cause: The scan finished but the anomaly's rows were not retrieved, for example because the anomaly was still being written when the recipe looked for it, or because you resumed the recipe in a session where the cached rows were gone. Loading them needs the Viewer team permission on the left datastore.

Resolution: On the Scan step, click Load Mismatch Records. If the button does not appear, click Run scan again.

Reconciling and Materializing

Some Mismatches Got No AI Suggestion

The footer reads "N mismatches got no AI suggestion. Retry them, or resolve those rows manually." or "No AI resolution suggestions arrived. You can retry, or resolve the mismatches manually."

Cause: Resolution recommendations are scored a few mismatches at a time, and the AI provider did not return a usable answer for some or all of them within the time allowed. They also need the AgentQ data sharing level Source Data Shared, because both sides' row values are sent to the model; below that level no recommendation arrives.

Resolution: Click Retry, or pick the side yourself in the Choose column. To enable the recommendations, ask your administrator to raise the data sharing level. See AgentQ Access Controls.

Next Stays Disabled on Reconcile

Every visible row seems resolved, but Next cannot be clicked.

Cause: Every loaded mismatch needs a pick, across all tabs. Rows on another tab, or on another page of the table, are still unresolved.

Resolution: Check the Mismatches resolved tile and the Changed, Added, and Removed tabs for rows without a pick.

Materialize Reports Nothing to Write

The Materialize step reads Nothing to materialize and offers Complete instead of Materialize.

Cause: Every mismatch was resolved in favour of the left asset, so its values already stand. The outputs are corrections only, and there are none.

Resolution: This is expected when the left asset is right. Click Complete; the anomaly is archived as Discarded. To correct the left asset from the reference instead, go back and pick Use right or Ignore row where appropriate.

The Remove Set Looks Stale

The Remove Set output in the enrichment destination lists rows from an earlier run.

Cause: The remove set is written only when the run has rows to remove. A run with none leaves the previous output in place, while the keep set is replaced every run.

Resolution: Compare the output with the mismatched rows count on the Complete step. When the run had no removals, treat the output as belonging to the earlier run, or delete it from the enrichment datastore.

The Anomaly Was Not Acknowledged

The keep set was written but the message Anomaly not acknowledged appeared, and the anomaly is still Active.

Cause: Acknowledging the anomaly after materializing needs the Author team permission on the left datastore, or the anomaly had been archived in the meantime.

Resolution: Acknowledge the anomaly from the Anomalies page once you have the permission. See Acknowledge Anomalies. The keep set is unaffected.

Resuming

The Recipe Restarted from the Beginning

Reopening Recipes shows Get Started instead of Continue, or the recipe opens on Select Assets although you had progressed further.

Cause: Progress is kept in your browser session, per recipe. A different browser or computer, a cleared session, or entering the recipe through Scan in Recipe or Reconcile in Recipe starts fresh.

Resolution: Nothing the run produced is lost. Open the active check and click Scan in Recipe to continue at the Scan step, or open its anomaly and click Reconcile in Recipe to continue at Reconcile. See Entry Points and Resuming.

Limitations

• The recipe compares one pair of assets at a time, and both must fit in your deployment's memory as a whole to be reconciled.
• Tolerances are set per field type, not per field. All numeric compare fields share one tolerance, as do all date and time fields and all text fields.
• The Reconcile step loads up to 10,000 mismatched rows. Larger sets are sampled, and picks by change type cover the rest.
• The remove set is only written when it has rows.
• Progress is not shared between browsers or users. Everything the run produced is.