Skip to content
More support Customer portal
  • There are no suggestions because the search field is empty.

 Understanding and Fixing "Sync in an Unknown State

If one of your integrations is showing a status of Sync in an Unknown State, here is what that means, why it happens across different vendors and PSAs, and how to clear it.


On this page

What "Unknown State" actually means

An unknown state simply means our sync engine could not confirm a clean success or a clean failure for that sync attempt. It is not a specific error on its own, it is a fallback status. Because of that, the exact cause is usually vendor-specific and needs a bit of troubleshooting on your end before reaching out to support.

 

Note: Seeing this status does not necessarily mean your data is wrong or that nothing has synced. It means the integration could not complete its usual confirmation step on the last attempt. In many cases, a fresh sync resolves it entirely.

 

First steps to try

  1. Force a fresh sync on the affected integration from its card on the Integrations page rather than waiting for the next scheduled sync.
  2. If the integration uses an authentication token or API key (rather than a stored username and password), re-authenticate it. Expired or rotated credentials are one of the most common causes of this status.
  3. Confirm your account and service mapping for that integration are complete. An incomplete mapping can prevent the sync from reaching a clean finish, even if authentication is fine.
  4. Give it a few minutes after a fresh sync before checking again. Larger accounts, or syncs that land during a busy sync window, can take longer to fully resolve.
 

 

Common causes

These are the most frequent reasons an integration lands in this state, based on recent support cases:

Expired or rotated vendor credentials

Some integrations use tokens that expire on a set schedule even if nothing looks wrong on your end. Pax8, for example, requires re-authentication roughly every 90 days. If a Pax8 integration was working fine and then suddenly shows this status, refreshing the token by hitting Authenticate again is usually all that is needed.

A shared or company-level admin account used for authentication

For vendors that also sync independently with other platforms in the background (for example, an email security vendor that syncs with your Microsoft tenant on its own schedule), using a shared admin mailbox for authentication can cause intermittent failures that surface as this status. Where possible, use a dedicated service account for the integration rather than a general admin or billing mailbox.

Vendor-side outage or rate limiting

If the vendor's own API is down or temporarily rate-limiting requests during your sync window, the sync can stop partway through without returning a clear error. This typically clears on its own within a few hours, and a forced resync afterward will confirm whether it has.

Sync queue timing

During our daily sync window, a large number of syncs run in a short period. If your manual sync lands during this window, it can take longer than usual to process and may briefly display this status before resolving on its own.

Tip: If you regularly do your reconciliation first thing in the morning, try running your manual sync a little later in the day. Landing outside the daily sync window generally means a faster, cleaner result.

 

When it happens on a PSA connection

This status can also appear on the PSA connection itself, not just on a vendor integration, most often right after a change to your PSA credentials, a cloud migration, or a change to API user permissions. If this happens on your PSA:

  • Confirm the API user or security role used for the connection still has the permissions outlined in your PSA's connection guide.
  • If you recently migrated your PSA (for example, moving to a cloud-hosted version), re-verify your credentials rather than assuming the migration carried them over automatically.
  • Run a full PSA sync rather than a quick sync to force a complete re-check.

Still stuck? Contact support

If you have re-authenticated, run a fresh full sync, and confirmed your mapping is complete, and the status still has not cleared after a few hours, reach out to support@meetgradient.com. Include:

  • The name of the integration or PSA affected
  • Roughly when you first noticed the status
  • Whether you have already tried a re-authentication or forced sync

This lets us check the sync activity directly on our end and get you a faster answer than starting from scratch.

Gradient Support Centre 🦩