My Vendor Sync Is Failing: Troubleshooting Decision Tree
This is the universal troubleshooting guide when a vendor sync is not working, regardless of which vendor it is. Most failed syncs fall into one of five categories, and the fix is usually under five minutes once you know which one you are dealing with.
Use this article when
- A vendor sync is showing as Failed, Stuck, or in Unknown State
- Vendor unit counts are not appearing or have stopped updating
- You see an Access Denied or API error from a vendor integration
- Sync has been running for hours and you do not know if it is hung
In this article
- Step 1: Identify what you are actually seeing
- Section A: Credentials and authentication
- Section B: Sync running for a long time
- Section C: A specific account or SKU is missing
- Section D: Custom or self-hosted script integration
- Section E: Counts are syncing but look wrong
- Still stuck? What to send support
Step 1: Identify what you are actually seeing
Before fixing anything, identify the symptom precisely. The fix depends entirely on this. Find your symptom in the table below.
| Symptom | Most likely category | Jump to |
|---|---|---|
| Integration shows “Unknown State” or “Failed” | Credentials or authentication | Section A |
| Sync has been running for over an hour | Sync in progress or queued | Section B |
| Counts populated initially but have stopped updating | Expired credentials | Section A |
| Counts are appearing but seem wrong | Mapping issue, not sync | Section E |
| API error or “Access Denied” message | Permissions or credentials | Section A |
| A specific account or SKU is missing, others are fine | Vendor-side configuration | Section C |
| Custom or self-hosted script integration not pulling | Script execution | Section D |
Section A: Credentials and authentication
Roughly 60% of vendor sync failures come down to expired or invalid credentials. The vendor side has rotated, expired, or revoked something Gradient depends on. Here is how to diagnose and fix it for the most common vendors.
OAuth-based integrations (Pax8, Microsoft)
These use OAuth tokens that expire on a schedule. Pax8 tokens expire every 90 days. Microsoft tokens can expire if GDAP or admin consent is revoked or refreshed.
- Navigate to Data Sources → Integrations
- Locate the affected integration and click Configure
- Click Authenticate (or Re-authenticate)
- Sign in with the same admin account you used originally
- Confirm sync resumes within a few minutes
Pax8 OAuth tokens expire every 90 days. If Pax8 was syncing fine and suddenly stopped, this is almost always the reason. Make sure you authenticate with a Pax8 Admin account, not a standard user.
API key based integrations (most vendors)
Most security, RMM, and backup vendors use API keys. When sync fails for one of these, the key has usually been rotated, deleted, or had its permissions reduced on the vendor side.
- In the vendor portal, locate API key management
- Check that the key Gradient uses still exists and is active
- Check that the API user it was created under has the required permissions
- If the key was deleted or rotated, generate a new one
- In Gradient, open the integration Configuration and paste the new key
- Click Save and Test, then wait for the sync to complete
| Vendor | Common cause of credential failure |
|---|---|
| Auvik | API key revoked in Auvik admin panel |
| SentinelOne | API token expired (S1 tokens have a configurable expiry) |
| Huntress | API key disabled or account permissions changed |
| SaaS Alerts | API token rotated, common after admin changes |
| Sophos Central | API credential expired, default lifespan is 12 months |
| Veeam SPC | Service account password changed |
| Cove (N-able) | Region mismatch or API key from wrong dashboard |
| Webroot | Parent Keycode or API user revoked |
| SonicWall | MySonicWall API access expired or partner number changed |
| Liongard | Service user disabled, or environment access removed |
| Ingram Micro | API password expired or marketplace code changed |
| Syncro | API token deleted or permissions modified |
AppRiver and other refresh-token integrations
AppRiver's refresh token has a 14-day expiry. Self-hosted scripts using AppRiver must run at least once every 13 days or the token expires and the script fails silently. If you find AppRiver is not updating, re-generate the token and update the script.
Section B: Sync running for a long time
A long-running sync is usually not a problem. Gradient runs two kinds of syncs and they behave very differently.
| Sync type | Typical duration | What it does |
|---|---|---|
| Quick Sync | 1 to 5 minutes | Pulls fresh vendor counts for already-mapped accounts and services |
| Full Sync | 10 minutes to 2+ hours | Pulls all accounts, services, and counts from scratch. Used after major PSA changes or on first connection |
| Ad-Hoc PSA Sync | 5 to 30 minutes | On-demand PSA refresh |
If sync has been running less than 30 minutes for a Quick Sync, or less than 2 hours for a Full Sync, it is most likely still working. Especially on first connection or after a major PSA change.
If it really is stuck
If sync has exceeded the expected duration by a meaningful margin, here is the recovery path:
- Refresh your browser — sometimes the status indicator stalls but the sync is actually complete
- Click the Status Refresh button on the integration
- Check Sync Status → Quick Sync All to trigger a fresh attempt
- If still stuck after 30 minutes, re-authenticate the integration (the underlying connection may have dropped)
- If still stuck, contact support@meetgradient.com with the integration name and the timestamp the sync started
Section C: A specific account or SKU is missing
If most data is flowing but one customer or one product is missing, the issue is almost always vendor-side configuration rather than the integration itself.
Customer missing
| Vendor | Check this first |
|---|---|
| Pax8 | Is the company marked Active in Pax8? Are all three required contacts (Billing, Technical, Primary) assigned? |
| Ingram Micro | Does the customer have the relevant SKU on their plan? Some SKUs only surface for customers actively subscribed to that product |
| SentinelOne | Is the customer site set up in the SentinelOne MDR platform with the right plan tier? |
| NinjaOne | Is the customer organization configured in NinjaOne with at least one device? |
| Auvik | Is the client active in Auvik and not archived? |
| Datto RMM | Was the API key created with the “Select Vendor” dropdown left blank? Keys with a vendor selected will silently fail |
| SaaS Alerts | Has the customer organization been added in SaaS Alerts? |
Product or SKU missing from the mapping list
This usually means the vendor's API is not exposing that SKU for that account, or Gradient does not yet support that specific SKU.
- Confirm the customer actually has that SKU active in the vendor portal
- Run a fresh sync (Quick Sync All) to see if it appears
- If the SKU exists in the vendor portal but not in Gradient's mapping screen, contact support@meetgradient.com with the customer name, vendor, and SKU name
Pax8 sometimes renames or consolidates SKUs (DropSuite, M365 commitment terms, Acronis editions). If a previously-mapped product disappears, check whether Pax8 has renamed it. The new name will be in the mapping screen — you just need to remap.
Section D: Custom or self-hosted script integration
Self-hosted scripts run on your infrastructure, not Gradient's. When they fail, there are a few extra places to check.
- Confirm the script has run recently — check the scheduled task or cron job logs
- Confirm the Gradient API token is still valid (these can be revoked from your Gradient account)
- Confirm the vendor API credentials embedded in the script are still valid
- Look for execution policy errors (PowerShell requires Unrestricted on the script's root folder)
- Check for 404 errors in the script output — these are normal and indicate an account or service has no mapping yet
Self-hosted scripts often produce 404 errors for accounts or services that have no mapping yet. These are expected and do not indicate a sync failure. Real failures will show authentication errors, connection errors, or 500-level errors.
For deeper script diagnostics, see: Custom and Self-Hosted Integration Troubleshooting.
Section E: Counts are syncing but look wrong
If sync is completing but counts do not match what you expect, the integration is working — the issue is mapping or vendor-side configuration. This is not a sync failure.
See the dedicated article: Counts and Discrepancy Troubleshooting.
Still stuck? What to send support
If none of the above resolved the issue, we can help faster if you email support@meetgradient.com with:
- The exact integration name (e.g. “Pax8”, “SentinelOne”, “Cove Data Protection”)
- What the integration status shows (Failed, Unknown, Pending, Active)
- When it last worked, if known
- A screenshot of the integration configuration page
- Any error message you have seen
- Whether you have tried re-authenticating or rotating credentials
Related articles