Troubleshooting Syncs and Credentials

Use this guide when data is stale, a sync fails, a connection pauses, or an external app needs to be reconnected.

Most sync issues fall into one of these categories:

Credentials expired or were revoked in the external app
Required permissions changed
Source data is empty or filtered out
A mapped table or column changed
The destination rejected records
A scheduled job is paused, failed, or waiting to retry

Quick Triage

Symptom	Start here
Data stopped updating	Check the source or destination app connection, then recent jobs.
Sync fails immediately	Check credentials, permissions, and required configuration.
Sync runs but returns zero rows	Check source filters, date windows, model output, or segment membership.
Destination rejects records	Check identity fields, field mappings, hashing, and destination API limits.
Counts differ across tools	Check downstream deduplication, attribution windows, and processing delays.
Job is paused	Check repeated failures, credential status, and whether the integration was manually paused.

Step 1: Check Connection Status

Open the app, source, or destination detail page and confirm:

The connection is active
The app is not paused
The last sync completed recently
There is no visible credential or permission error
The connected account, project, workspace, or dataset is the expected one

If an external admin removed access, changed a password, rotated an API key, or revoked OAuth consent, reconnect the app before retrying the sync.

Step 2: Check Recent Jobs

Open the related job history and inspect the latest run.

Job state	Meaning
Pending	Vendo created the job and it is waiting to be scheduled.
Queued	Vendo accepted the job and is waiting to run it.
Running	Work is in progress. Large historical syncs can take longer than scheduled incremental syncs.
Completed	Vendo finished the job. Check row counts and destination acceptance if output looks wrong.
Errored	The job ended with an error. Read the first error and final error.
Canceled	The job was stopped by a user or by the system.

A source or integration can also be paused — the pipeline itself is disabled or blocked, often after repeated failures or a manual pause, so no new jobs are created until it is resumed.

The first error usually points to the root cause. Later errors may only show retry state or downstream effects.

Step 3: Check Credentials

Credential issues are common after security changes in external tools.

OAuth Connections

Reconnect the app if:

The user who authorized the app left the company
The external app forced a password reset
Admin permissions changed
OAuth consent was revoked
The provider reports invalid_grant, unauthorized, permission_denied, or similar errors

After reconnecting, rerun a small sync before running a large backfill.

API Key Connections

Check:

The API key is still active
The key has the required scopes
The key belongs to the expected account or workspace
The key was not rotated without updating Vendo
IP allowlists or API restrictions still allow Vendo

Service Accounts

For warehouse destinations and sources, confirm:

The service account still exists
The service account has read/write access to the expected project, dataset, bucket, or table
The project or dataset was not renamed
Billing is active in the cloud account
The private key or credential JSON was not revoked

Step 4: Check Permissions

Credentials can be valid but still lack permission.

Common examples:

A Google Ads user can view campaigns but not conversion actions
A Meta user can access an ad account but not upload conversions
A warehouse service account can read tables but not create output tables
A messaging tool key can read profiles but not update subscriptions
A CRM token can access contacts but not custom objects

If permissions changed, update them in the external app and reconnect if required.

Step 5: Check Source Data and Date Windows

If a sync succeeds with zero or fewer rows than expected:

Confirm the external source has data for the selected period.
Check date filters and lookback windows.
Confirm the source account or workspace is correct.
Check whether the source API delays recent data.
Check whether the integration filters out test, deleted, or invalid records.

For historical backfills, start with a small date range to verify configuration before running the full range.

Step 6: Check Schema and Mapping Changes

Schema drift can break a sync that worked previously.

Look for:

A source column was renamed or removed
A model output column changed type
A destination field became required
A table moved to a different dataset
A nested object or array no longer matches the destination format

To recover:

Refresh or reopen the mapping.
Remap missing fields.
Save the integration.
Run a test sync.
Monitor the next scheduled run.

Step 7: Check Identity Requirements

Destinations often require identity fields. Missing identities can make a successful sync deliver zero accepted records.

Common required identifiers:

Email
Phone
User ID or external ID
Anonymous ID
Platform-specific ID
Click ID or conversion ID
Mobile advertising ID

If identifiers are missing, review Identity Resolution, rerun resolution, then rerun the destination sync.

Step 8: Retry Safely

Before retrying:

Fix the root cause first
Use a small date range when possible
Avoid rerunning multiple full backfills at once
Confirm deduplication fields are present for event destinations
Monitor job logs after retrying

If a job has already delivered partial data, check whether the destination deduplicates records before retrying the same period.

When to Escalate

Escalate if:

A job remains queued or running much longer than normal
Credentials were reconnected but the same auth error returns
A source API appears healthy but Vendo receives no data
A destination reports success but records never appear downstream
The same integration fails repeatedly after mapping and credential fixes

Include:

Account/workspace name
Source or destination app
Integration or job ID
Time window affected
First error message from the job log
Any recent changes to credentials, permissions, mappings, or source schema