/diagnosing-failed-warehouse-syncs

name: diagnosing-failed-warehouse-syncs
description: >
  Diagnose why a data warehouse sync is failing and recommend the right recovery action. Use when the user asks "why
  isn't my Stripe/Postgres/Hubspot sync working?", "this table has been stuck for hours", "the data in the warehouse
  looks wrong", or wants to troubleshoot a specific source or schema. Covers source-level vs schema-level failures,
  stuck Running states, credential and schema-drift errors, incremental-field misconfig, CDC prerequisite failures,
  and the cancel / reload / resync / delete-data recovery actions.

Diagnosing failed data warehouse syncs

Work top-down when a data warehouse source or table is failing, stuck, or producing bad data: source → schema → recovery action. Do **not** jump straight to "resync from scratch" — that discards synced data and restarts from zero, which is rarely the right first step.

When to use this skill

• The user reports a specific sync is failing (e.g. "my Stripe source is red")
• A table has been in `Running` state far longer than expected
• Data in a warehouse table is stale, missing rows, or looks corrupt
• Latest rows aren't appearing despite the schema being marked `Completed`
• The user is choosing between cancel / reload / resync / delete-data and isn't sure which
• Another skill — typically `auditing-warehouse-source-health` — has surfaced a failing source or schema and the user

wants to dig into it

Both entry points (user-reported and audit-handoff) use the same workflow; the audit just means you already know which item to diagnose and can skip Step 1's discovery search.

Available tools

| Tool | Purpose | | ------------------------------------------------------ | -------------------------------------------------------------------------- | | `external-data-sources-list` | List all sources with connection status and latest error | | `external-data-sources-retrieve` | Full details for one source including all its schemas | | `external-data-schemas-list` | All table schemas across all sources, with per-table status + latest_error | | `external-data-schemas-retrieve` | Full details for one schema including sync_type_config | | `external-data-schemas-cancel` | Cancel a sync currently in `Running` state | | `external-data-schemas-reload` | Trigger a sync using the configured sync method (respects incremental) | | `external-data-schemas-resync` | Full resync — wipes synced data and restarts. Destructive | | `external-data-schemas-delete-data` | Delete the synced table but keep the schema entry | | `external-data-schemas-partial-update` | Change sync_type / incremental_field / cdc_table_mode | | `data-warehouse-source-connect-link` | Secure browser link where the user re-enters a source's credentials | | `data-warehouse-stored-credentials-list` | Find the `credential_id` the user stored on the connect page | | `external-data-sources-partial-update` | Reconnect a source with `{"payload": {"credential_id": ...}}` | | `external-data-sources-reload` | Retrigger syncs for every enabled schema on a source | | `external-data-sources-refresh-schemas` | Re-fetch the source's table list to pick up new tables | | `external-data-sources-check-cdc-prerequisites-create` | Verify Postgres CDC setup for a source | | `external-data-sources-cdc-status-retrieve` | Live CDC health: slot, publication, lag, paused schedule | | `external-data-sources-resume-cdc-create` | Unpause CDC after a fixed failure, no re-snapshot | | `external-data-sources-repair-cdc-create` | Recreate a lost slot or publication. Forces a full re-sync | | `external-data-schemas-incremental-fields-create` | Refresh candidate incremental fields when the source schema has changed | | `external-data-sources-webhook-info-retrieve` | Check webhook registration state and external service status | | `external-data-sources-create-webhook-create` | Re-register a webhook that was lost or never registered | | `external-data-sources-update-webhook-inputs-create` | Update the signing secret after rotation on the source side | | `external-data-sources-delete-webhook-create` | Remove a broken webhook before re-registering | | `platform-alerts-list` | Check whether a sync failure alert already exists | | `platform-alerts-create` | Create a sync failure alert for a source or its tables | | `warehouse-alerts-destinations-create` | Choose where the alert notifies (Slack, webhook, and so on) |

Workflow

Step 1 — Locate the failing item

If the user named a source, go straight to `external-data-sources-retrieve`. Otherwise start with `external-data-sources-list` and `external-data-schemas-list` to find what's red.

Two kinds of failure:

• **Source-level** (`ExternalDataSource.status = "Error"`): the connection itself is broken — credentials expired,

host unreachable, account disabled. Affects every table.

• **Schema-level** — the source connects fine but one or more tables are failing. In the serialized API respon