# Scan Troubleshooting

Source: https://userguide.qualytics.io/operations/scan/troubleshooting/

This page documents known scan-related errors and the steps to resolve them. Each section describes the error, its cause, and a step-by-step resolution. For how a Scan's final result is decided, what "success with warnings" means, and the full list of failure codes, see [Scan Outcomes](https://userguide.qualytics.io/operations/scan/deep-dive/scan-outcomes/).

## Connection Interrupted During a Scan

When running a scan, you may see an error like the following for one or more containers:

```text
The connection to your source datastore was interrupted while reading '<CONTAINER_NAME>'.
```

**Cause:** The source database ended a connection that was already open while Qualytics was reading data. This is usually not a data-quality problem and not a problem with your connection settings. Common triggers include:

- A maintenance or load window on the source that restarts services or ends long-running sessions.
- A database administrator or server policy that ends long-running read sessions.
- A network device (firewall, load balancer, or VPN) that resets long-lived connections.

Because the interruption is temporary, re-running the same scan usually succeeds. Scans that read very large tables, or that overlap a scheduled data load on the source, are the most likely to be affected. This is also why the same scan can take noticeably longer on one run than another.

**Resolution:**

1. Re-run the scan. Qualytics automatically retries a read that is interrupted this way, so a fresh run often completes on its own.
2. If the failures keep happening, schedule scans to run outside the source's maintenance or data-load window. See [Schedule Options](https://userguide.qualytics.io/operations/scan/how-tos/schedule-options/).
3. For large, frequently updated tables, use an [Incremental scan](https://userguide.qualytics.io/operations/scan/deep-dive/read-strategies/#incremental) so each run reads only new or changed records and spends less time connected to the source.
4. If the source is heavily loaded during your scan window, consider pointing the datastore at a read replica or reporting copy of the database.

> **Note**
>
> Qualytics reads relational sources without blocking writes, so scanning does not lock the tables being read. Interruptions of this kind come from the source ending the connection, not from Qualytics holding locks on it.

---

## A Scheduled Scan Fails Over Its Selected Checks

A scheduled scan that picked specific checks ends in **Failure**, and its message says that none of its selected checks is still active and asks you to update the schedule's check selection.

**Cause:** Every check the schedule picked has since been archived, set to draft, or deleted, or no longer belongs to the categories the schedule selects. A schedule drops picks that are no longer active and keeps asserting the rest, but it cannot run with none left, and it does not fall back to asserting every check.

**Resolution:**

1. Open the schedule and go to **Select Check Categories**.
2. Pick at least one active check, or select **All** to assert every active check in the chosen categories, and save. Picks that are no longer active are dropped when you save.

> **Note**
>
> Saving the schedule is refused while no active check is picked. The same applies through the API: a schedule whose `check_ids` no longer resolve to active checks has to be updated with a new selection, or with `check_ids` left out.

---

## Unloadable Container Error

When running a scan, a profile, or a quality check validation, you may encounter the following error for specific containers:

```text
Container '<CONTAINER_NAME>' is marked as Unloadable. No attempt was made to load the container due to multiple consecutive failures in prior operations.
```

**Cause:** This error occurs when a container has failed in 3 consecutive scan or profile operations for a reason that points to the container itself, such as a table that no longer exists, a missing permission, or a configuration error. The count combines scans and profiles chronologically.

- **What does not count:** temporary failures, such as a timeout, an interrupted connection, an inactive warehouse, or a quota limit, and failures on the Qualytics side. They neither add to the count nor reset it. A container whose scan or profile was aborted before it finished does not count either. When you abort a Run, the containers that had already failed before the abort still count.
- **What resets the count:** a scan or profile that reads the container successfully, even when writing its results to the enrichment datastore failed. A container whose scan or profile was aborted does not have its Unloadable status cleared.

To prevent repeated failed attempts and optimize performance, Qualytics marks the container as "Unloadable" and skips it in subsequent operations. Any later attempt to use the container (running another scan or profile, or validating a quality check against it) surfaces the same error until the status is cleared.

**Resolution:** The steps to clear the **Unloadable** status depend on the container type. Hovering over the container's status indicator in the app shows the same guidance, so you can tell which of the two paths below applies without leaving the page.

### Tables, views, and file patterns

These containers are discovered from the datastore catalog, so a successful Sync operation resets their status.

1. Navigate to your source datastore.
2. Run a [Sync Operation](https://userguide.qualytics.io/operations/sync/sync/) on the datastore.
3. Once the sync operation completes successfully, the container status is reset.
4. Re-run the operation that surfaced the error (scan, profile, or check validation). The previously unloadable container should now process normally.

### Computed assets ([Computed Tables](https://userguide.qualytics.io/container/computed-tables/getting-started/), [Computed Files](https://userguide.qualytics.io/container/computed-files/getting-started/), [Computed Joins](https://userguide.qualytics.io/container/computed-join/getting-started/))

Computed assets are defined inside Qualytics, not discovered from the datastore catalog, so a Sync operation does not reset their status. Instead, you need to force an edit on the asset and re-save its definition. Re-saving runs the validation against the datastore again and clears the **Unloadable** status.

1. Navigate to the source datastore where the computed asset lives.
2. Open the computed asset and click **Edit** to force the asset into edit mode.
3. Review the SQL query or transformation and apply any change needed to make it work again (for example, after a renamed source column, a removed table, or a schema change in an upstream container). If the definition still looks correct, you can re-save it as-is to force Qualytics to re-evaluate it.
4. Click **Validate** to confirm the query runs successfully against the datastore.
5. Click **Save**. Saving a successfully validated definition clears the **Unloadable** status, and the asset becomes available again for scans, profiles, and check validations.

For details on editing computed assets, see [Computed Tables](https://userguide.qualytics.io/container/computed-tables/how-tos/edit/), [Computed Files](https://userguide.qualytics.io/container/computed-files/how-tos/edit/), and [Computed Joins](https://userguide.qualytics.io/container/computed-join/how-tos/edit-a-computed-join/).

> **Tip**
>
> If the container continues to fail in scans, profiles, or check validations after a Sync (tables, views, or file patterns) or after Validate + Save (computed assets), investigate the underlying cause of the failures. Common causes include:
>
> - Permission issues accessing the container.
> - Schema changes that invalidate existing configurations.
> - Network connectivity problems to the data source.
> - Resource constraints or timeouts during data loading.
> - For computed assets: SQL referencing a renamed, dropped, or relocated upstream object.

*Last updated: November 4, 2026.*