Skip to content

Expected Schema Troubleshooting

Common problems when creating and running an Expected Schema 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 rule could not read the container's structure. The most common reasons are a connection problem with the source or a container that failed to load.

Resolution:

  1. Review the error message: it explains what needs attention.
  2. 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.

Every Scan Reports an Undeclared Column

The check fires on a column that is legitimately there.

Cause: Allow other fields is off, so the container must hold exactly the declared set.

Resolution: Turn the toggle on when the table is shared and other teams add columns, or add the column to the declaration when it is part of your contract.

A Column Is Reported as Missing After a Rename

Nothing was dropped, but the check reports a missing field.

Cause: A rename reads as the declared field being absent. For anyone binding to the old name, it is gone.

Resolution: Update the declaration to the new name as part of shipping the rename.

A Type Change Is Reported but the Data Looks Fine

The values are readable, yet the check fails on the type.

Cause: The declared type is part of the contract. A number arriving as text still fails, even when every value would convert cleanly.

Resolution: Fix the type upstream, or update the declaration when the new type is intentional. To assert that text values are convertible rather than that the column is typed, use Is Type.

There Is No Filter or Coverage Option

The form shows neither a Filter Clause nor a Coverage slider.

Cause: Both are row-level concepts, and this rule reads the container's structure. They are absent from the form, and the API rejects a non-empty filter or a coverage other than 1 with 422.

Resolution: No action needed.

An Edited Check Keeps Behaving the Old Way

You changed the configuration but the anomaly list did not change.

Cause: Edits take effect on the next Scan. Saving the check does not re-evaluate 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.

No Anomalies Although the Data Looks Wrong

A Scan ran, the data clearly breaks the rule, but nothing was reported.

Cause: The check is in Draft status, and Draft checks are not evaluated by Scans.

Resolution: Confirm the check is Active, then run a Scan on the container.