Sync Problems
CLARITY automatically syncs data from your connected cloud providers on a regular schedule. This guide helps diagnose and resolve sync-related issues.
Understanding the Sync Cycle
CLARITY runs automatic data syncs on a periodic schedule:
- Automatic syncs run every 12 hours by default
- Manual syncs can be triggered from the dashboard at any time
- Cooldown period — A minimum of 1 hour must pass between syncs for the same account to prevent excessive API usage
- First sync runs immediately when you add new cloud credentials
Each sync collects cost data, resource inventories, usage metrics, and optimization recommendations from the cloud provider APIs.
Sync Status Indicators
The sync status is displayed in the dashboard header and on the accounts page:
| Status | Meaning |
|---|---|
| In Progress | Sync is actively running. This may take several minutes. |
| Completed | Sync finished successfully. Data is up to date. |
| Failed | Sync encountered an error. Check the error details below. |
Common Sync Failures
Invalid Credentials
Symptoms: Sync fails immediately with an authentication error.
Causes:
- AWS access key was deactivated or deleted
- Azure service principal secret expired
- GCP service account key was rotated
Solution: Update the credentials on the accounts page with valid, active keys.
Insufficient Permissions
Symptoms: Sync partially completes but some data categories are missing.
Causes:
- IAM role or policy was modified after initial setup
- Required permissions were removed from the service principal
- A new AWS service was added but the IAM policy does not cover it
Solution: Review the required permissions for your provider in the Quickstart Guide and restore any missing permissions.
API Rate Limiting
Symptoms: Sync fails partway through with timeout or throttling errors.
Causes:
- Cloud provider API rate limits exceeded (especially Azure, which returns 429 errors)
- Multiple tools or users querying the same cloud account simultaneously
Solution: Wait for the cooldown period to pass and trigger a new sync. CLARITY handles rate limiting with automatic retries, but sustained throttling may cause a sync to fail.
Network Connectivity
Symptoms: Sync fails with connection timeout errors.
Causes:
- CLARITY instance cannot reach cloud provider APIs (firewall rules, DNS issues)
- Deployment behind a restrictive corporate proxy
Solution: Verify that the CLARITY instance can reach the following endpoints:
- AWS:
ce.us-east-1.amazonaws.com,ec2.*.amazonaws.com,monitoring.*.amazonaws.com - Azure:
management.azure.com,login.microsoftonline.com - GCP:
bigquery.googleapis.com,compute.googleapis.com,monitoring.googleapis.com
Triggering a Manual Sync
To manually trigger a sync:
- Navigate to the Dashboard or Accounts page
- Click the Sync button next to the account you want to refresh
- Wait for the sync to complete (status indicator will update)
INFO
Manual syncs respect the 1-hour cooldown. If you triggered a sync recently, you will need to wait before triggering another.
What to Do If Sync Is Stuck
If a sync appears stuck in the "In Progress" state for more than 15 minutes:
- Wait — Large accounts with thousands of resources can take up to 10-15 minutes
- Check logs — If you have access to the application logs, look for error messages or timeouts
- Restart the application — If the sync is truly stuck, restarting the application will clear the in-progress state
- Trigger a new sync — After restart, trigger a fresh manual sync
Next Steps
- Review Common Issues for other problems
- Check the Glossary for terminology