When a Sync Breaks: A Fivetran Failure Triage Runbook

Every Fivetran account eventually produces the same Monday morning: a dashboard is stale, a connector is red, and three people are asking whether the number in the board deck is wrong. The platform is managed, so the instinct is to open a support ticket and wait. Most of the time you do not have to - the majority of sync failures fall into a small number of recognisable classes, and each has a known first move.

This is the triage runbook we hand to clients when we take over a Fivetran estate. It assumes nothing beyond account access and read access to the destination.

Triage in four questions

Before touching anything, answer these in order. They narrow the problem faster than reading the error text.

1. Is it one connection or many? Many connections failing at once means destination, credentials or networking. One connection means the source.
2. Did it ever work? A connection that has never completed an initial sync is a setup problem. A connection that worked for nine months and stopped is a change problem - something moved on the source, destination or network side.
3. Is it failing, or just slow? A sync that is still running is not a failure. Check the status: SYNCING with a growing duration is a volume or throughput issue, not an error, and cancelling it may cost you a restart from scratch.
4. When did it last succeed? The gap between last success and now is your data-loss window and the first thing stakeholders will ask for. Get the number before you start fixing.

The Fivetran UI gives you the first three. For the fourth, and for anything historical, query the Platform Connector tables in your warehouse rather than clicking through the log viewer - connection_sync_start, connection_sync_end and log give you a durable history the UI does not surface well. If you have not set that up, the pipeline observability walkthrough covers it.

The failure classes, and what to do about each

1. Expired or rotated credentials

By far the most common cause of a connection that worked and then did not. OAuth refresh tokens expire, a password rotation policy fires, a service account gets deprovisioned when someone leaves, an API key is cycled during an unrelated incident.

Symptoms: authentication or authorisation errors on a single connection, often several connections to the same source system at once.

First move: re-authorise the connection rather than editing fields. For OAuth sources, a fresh authorisation flow replaces the token cleanly; patching a client secret by hand frequently leaves a half-valid state. Then fix the root cause: move the integration onto a dedicated, non-expiring service account that is owned by a team rather than a person, and put its rotation date in a calendar that outlives the project.

2. Source permission drift

A close cousin, and nastier because it fails partially. A new table appears, the sync picks it up, and the Fivetran user has no SELECT on it. Or a DBA tightens grants and one schema silently drops out.

Symptoms: the connection succeeds overall but a table is missing or stuck; or setup tests fail on a subset of objects.

First move: re-run the connection's setup tests - they enumerate exactly what the user cannot read. Then grant at the schema level with default privileges for future objects, not table by table. Table-by-table grants guarantee this ticket comes back.

3. CDC mechanics on database sources

The most expensive class, because the failure mode is often "you must re-sync". Watch for:

• Postgres replication slot lag or removal. A paused connector keeps its slot open and WAL accumulates until the disk fills; a helpful DBA then drops the slot and your log position is gone.
• MySQL binlog expiry. If binlog_expire_logs_seconds is shorter than your longest outage, the position Fivetran holds is no longer on disk.
• SQL Server CDC cleanup jobs trimming change tables faster than the sync interval.
• Failover. A replica promotion changes LSN/log lineage and frequently forces a re-sync.

First move: check log retention on the source before anything else, and compare it to the time since last success. If retention has passed, you are re-syncing - plan it deliberately with the backfill strategy rather than clicking Re-sync on a billion-row table at 09:00. Prevention is simple and nobody does it: set log retention to comfortably exceed your worst-case incident response time, and alert on replication slot lag.

4. Schema and type changes on the source

A column type changes, a primary key is dropped, a table is renamed, a column exceeds a destination's limits. Fivetran handles most of this automatically, but some changes require a table re-sync and some land as a new column alongside the old one, quietly splitting your data.

Symptoms: a table in a "rescheduled" or blocked state, or downstream dbt models failing on types while Fivetran reports success.

First move: look at what changed in the source release, not at Fivetran. Then decide the handling policy deliberately - the schema drift playbook covers change-handling settings and the re-sync decision. The durable fix is social: get yourself onto the notification path for source schema changes so you find out before your warehouse does.

5. Destination errors

Symptoms here are the giveaway: many connections failing simultaneously with the same message.

Common causes: warehouse credentials rotated; the destination role lost CREATE TABLE on a schema; the warehouse is suspended or out of credits; a storage quota or Fabric capacity is exhausted; a staging bucket policy changed.

First move: run the destination setup test. It isolates destination from source in one click. If the destination is healthy, you are looking at a coincidence of per-connection problems - rare, but it happens after an org-wide credential rotation.

6. Networking

Symptoms: connection timeouts, "host unreachable", intermittent failures that resolve on retry.

Causes are nearly always a change on your side: a security group edit, a rotated SSH key, a bastion instance replaced by autoscaling, a dead reverse tunnel, new egress IPs not yet allowlisted, a DNS change on a PrivateLink endpoint.

First move: test from inside your own network - can a host in the same subnet reach the database port? If yes, the problem is in the path from Fivetran to that subnet. The private networking guide lists the four checks that resolve most of these.

7. Source API limits and vendor-side incidents

Symptoms: rate-limit errors, partial syncs, or a connection that takes dramatically longer than usual on a SaaS source.

Salesforce API allocation, Google Ads quota, NetSuite concurrency limits and HubSpot rate caps all behave this way, and they are frequently caused by something other than Fivetran consuming the quota - a middleware job, a backup tool, another integration. Before raising a ticket, check the source's own API usage dashboard. For Salesforce specifically, object selection and formula fields are usually where the budget is going.

Also check the vendor's status page and Fivetran's. Not every incident is yours.

Stabilise before you fix

When something is genuinely broken and the fix will take hours:

• Pause, do not delete. Deleting a connection destroys its state; re-creating it means a full historical re-sync and a MAR bill to match. Pausing is almost always reversible - but remember pausing a database connection keeps the replication slot open, so watch source disk.
• Narrow the blast radius. Deselect the one broken table so the other forty keep flowing, rather than leaving the whole connection red.
• Tell downstream consumers the freshness number. "Last successful sync was 06:15, data after that is missing" is a usable statement. "The pipeline is broken" is not.
• Do not fire a blind re-sync. It is the most expensive button in the product. Scope it to the affected table, and know what it will cost in MAR before you press it - the connection-level MAR pricing article explains how that is counted.

Close the loop

After recovery, two artefacts should exist. First, an alert that would have caught it earlier - a freshness threshold per connection, not a global one, because a daily marketing connector and a 15-minute CDC connector have different definitions of late. Second, a line in the runbook: symptom, cause, fix, owner. Estates that run quietly are not the ones with fewer incidents; they are the ones where the same incident never costs a full morning twice.

If your Fivetran estate is currently in the state where nobody is quite sure which connections matter and alerting is somebody's inbox rule, that is the work we do. SyncSpur provides maintenance and support for Fivetran platforms and takes on stalled or inherited Fivetran projects. Get in touch with the list of connections you are worried about and we will start from the same four questions above.