Data Source Sync Failures: Timeouts, Auth Expiry, Quotas

Overview

Data source syncs keep your clariBI dashboards and reports up to date. When a sync fails, affected dashboards show stale data and scheduled reports may not generate correctly. This guide covers every common sync failure, what causes it, and how to fix it.

You can check sync status at any time by going to Data Sources in the left sidebar. Data sources with sync problems show a red Error badge or a yellow Warning badge.

Error: Connection Timeout

Message: "Sync failed: connection timed out after 60 seconds."

Cause: clariBI could not establish a connection to the external data source within the timeout period.

Common Reasons

• The external database or API server is down or unreachable
• A firewall is blocking the connection from clariBI's servers
• DNS resolution is failing for the host address
• The database is under heavy load and not accepting new connections

How to Fix

1. Check the external service. Log in to your database or API provider and verify the service is running.
2. Verify network access. If your database is behind a firewall, make sure clariBI's IP addresses are whitelisted. Contact support@claribi.com for our current IP range.
3. Test the connection. In clariBI, go to the data source settings and click Test Connection. The test provides more specific error details than the sync log.
4. Check connection credentials. If the host, port, or database name changed, update them in the data source configuration.
5. Try a manual sync. Click Sync Now after fixing the connection. If the manual sync works, the next scheduled sync should also succeed.

Error: Authentication Expired

Message: "Sync failed: authentication credentials are invalid or expired."

Cause: The OAuth token, API key, or database password used for the connection is no longer valid.

For OAuth Connections (Google Ads, Meta Ads, Google Analytics, etc.)

OAuth tokens expire periodically: - Google: Tokens last several months but can be revoked by the user - Meta: Tokens expire after 60 days - Salesforce: Tokens expire based on your org's session settings

How to fix: 1. Go to Data Sources and click the affected source. 2. Click Re-authenticate. 3. Complete the OAuth flow (sign in and grant permissions). 4. Click Sync Now to verify the new token works.

For Database Connections

Database passwords may change when your DBA rotates credentials.

How to fix: 1. Go to Data Sources and click the affected source. 2. Click Edit Connection. 3. Update the username and/or password. 4. Click Test Connection to verify. 5. Click Save.

For API Key-Based Connections

If the external service's API key was rotated or revoked:

1. Generate a new API key in the external service.
2. In clariBI, go to Data Sources > [Source] > Edit Connection.
3. Update the API key.
4. Test and save.

Error: Rate Limited

Message: "Sync failed: rate limit exceeded. Retry scheduled for [time]."

Cause: The external API returned a rate limit error (HTTP 429). This happens when clariBI (or other clients) are making too many requests to the API.

How to Fix

1. Wait for the retry. clariBI automatically retries rate-limited syncs after a delay (usually 15-60 minutes).
2. Reduce sync frequency. If this happens regularly, change the sync from hourly to every 6 hours or daily. Go to Data Sources > [Source] > Settings > Sync Frequency.
3. Check other clients. If other tools are also hitting the same API, the combined request volume may exceed the rate limit.
4. Contact the API provider. Some providers offer higher rate limits on paid plans.

Error: Quota Exceeded

Message: "Sync failed: API quota exhausted for the current billing period."

Cause: The external API has a monthly or daily request quota, and it has been reached.

Common Quota Limits

How to Fix

1. Wait for the quota to reset. Most quotas reset daily or monthly.
2. Reduce the data scope. Sync fewer tables, fewer metrics, or a shorter date range.
3. Decrease sync frequency. Switch from hourly to daily syncs.
4. Upgrade the external service. If you are on a free tier, upgrading often increases quotas significantly.
5. Consolidate syncs. If multiple clariBI data sources hit the same API, consider combining them into one data source with a broader scope.

Error: Schema Mismatch

Message: "Sync failed: table [table_name] does not exist or column [column_name] was removed."

Cause: The structure of the external data source changed since the connection was configured. A table was renamed, a column was dropped, or the schema was reorganized.

How to Fix

1. Go to Data Sources > [Source] > Schema.
2. Click Refresh Schema to pull the latest structure.
3. Review the changes. clariBI highlights added, removed, and modified columns.
4. Update any dashboard widgets or report templates that reference the changed columns.
5. Click Sync Now to verify.

If a table was completely removed, you need to update the data source configuration to point to the replacement table.

Error: Sync Partially Failed

Message: "Sync completed with errors: X of Y tables synced successfully."

Cause: Some tables synced but others failed. This usually happens when individual tables have different permissions or when one table is exceptionally large.

How to Fix

1. Check the sync log for the specific tables that failed. Go to Data Sources > [Source] > Sync History and click the most recent sync.
2. Each failed table shows its own error message (timeout, permission denied, etc.).
3. Fix the underlying issue for each failed table.
4. Run a manual sync to retry all tables.

Error: SSL/TLS Handshake Failed

Message: "Sync failed: SSL handshake error."

Cause: There is a problem with the SSL certificate on the database server.

How to Fix

1. Check the certificate. Ensure the database server's SSL certificate is valid and not expired.
2. Verify SSL settings. In the data source configuration, check whether SSL is enabled or disabled. Some staging databases use self-signed certificates.
3. If using a self-signed certificate: Enable the "Allow self-signed certificates" option in the data source's advanced settings (if available).
4. Contact your DBA. Certificate issues usually need to be resolved on the database server side.

Monitoring and Alerts

Setting Up Sync Failure Notifications

clariBI can notify you when a sync fails:

1. Go to Settings > Notifications.
2. Enable Data Source Sync Alerts.
3. Choose notification channels: in-app, email, or both.
4. Optionally set a threshold -- notify only after X consecutive failures to avoid alerts for one-off issues.

Viewing Sync History

Every data source maintains a sync history log:

1. Go to Data Sources > [Source] > Sync History.
2. The log shows:
3. Sync start and end time
4. Status (Success, Failed, Partial)
5. Records synced
6. Error message (if failed)
7. Duration

Use this log to identify patterns. If syncs fail at the same time every day, the external service may have a maintenance window.

Automatic Retry Behavior

When a sync fails, clariBI retries automatically:

After 3 consecutive failures, the data source is marked as Error and sync is paused. You receive a notification prompting you to investigate.

To resume syncing after fixing the issue, go to the data source and click Resume Sync.

Best Practices

• Set up notifications early. Do not wait for a dashboard to show stale data before discovering a sync failure.
• Use daily syncs as a default. Hourly syncs are rarely necessary and increase the chance of hitting rate limits.
• Keep credentials up to date. When you rotate passwords or API keys for external services, update the clariBI data source immediately.
• Monitor the sync history. A weekly check of your data source sync logs catches intermittent issues before they become chronic.
• Document your data sources. Use the description field in each data source to note who manages the external service, what credentials are used, and when they were last rotated.

Related Articles

• Connecting Your First Data Source
• Dashboard Won't Load: Step-by-Step Diagnosis
• Report Generation Failures: Every Error and Fix
• Google Ads and Meta Ads: OAuth Setup and Metrics
• BigQuery: Connecting Datasets and Running Queries