When an integration stops working, PartnerOS surfaces alerts in Settings > Integrations and records every event in the audit log. Most failures fall into one of five patterns. This page walks through each one: what you will see, why it happens, and how to fix it.Documentation Index
Fetch the complete documentation index at: https://docs.partneros.ai/llms.txt
Use this file to discover all available pages before exploring further.
To access the audit log for a connection, go to Settings > Integrations, click the connection card, and scroll to the Audit Log section. You can filter by event type to narrow down the failure. The audit log records every sync operation, token refresh, mapping change, and schema event.
Quick reference
Use this table to identify the issue and jump to the right section.| What you see | Alert type | Audit event to look for | First action |
|---|---|---|---|
| ”Token revoked” banner | Critical | token.refresh_failed | Reconnect OAuth |
| ”Schema drift detected” banner | Warning | schema.drift_detected | Refresh Schema |
| ”Rate limit low” banner | Warning | rateLimitRemaining in sync metadata | Pause syncs, wait |
| Last Sync date is not advancing | None | sync.* events with errors | Review errors, fix mappings |
| No new data despite CRM changes | None | No recent sync.pull events | Verify CDC config, run full sync |
Common integration errors
Token revoked (OAuth 401)
Token revoked (OAuth 401)
When Salesforce or HubSpot invalidates the access token that PartnerOS holds, all sync operations fail immediately with 401 errors. No data flows in either direction until you reauthorize.
What you will see
- The connection card in Settings > Integrations shows Reconnect required with a red indicator.
- A critical alert banner reads “Token revoked.”
- Filtering the audit log by event type
token.refresh_failedshows recent failures with timestamps. - Sync operations (
sync.push,sync.pull) show HTTP 401 errors in their audit log metadata.
Why this happens
Salesforce:- A Salesforce user or admin removed PartnerOS from Setup > Apps > Connected Apps > Manage Connected Apps.
- A Salesforce admin tightened org-wide OAuth policies (for example, requiring admin pre-approval for OAuth apps) without adding PartnerOS to the approved list.
- The refresh token expired. Salesforce refresh tokens expire based on the Connected App’s configured timeout (the default is 1 year, but your org may have a shorter policy).
- The Connected App definition was modified, which invalidates existing token grants.
- A Salesforce security policy invalidated all OAuth tokens when a user changed their password.
- The app was removed from HubSpot’s Connected Apps settings.
How to fix it
Click Reconnect on the connection card
In Settings > Integrations, find the affected connection and click Reconnect (or Reconnect Salesforce / Reconnect HubSpot). This starts a fresh OAuth authorization flow.
Complete the consent screen
Log in to Salesforce or HubSpot and click Allow to grant all requested permissions. Do not remove any scopes.
Confirm the connection is active
After the redirect back to PartnerOS, verify the connection status returns to Active.
Trigger a manual sync
On the connection detail page, click Trigger Sync to confirm data flows correctly with the new token.
How to prevent it
- Monitor the connection status in Settings > Integrations — PartnerOS alerts you automatically when a 401 is detected during sync.
- Coordinate with your Salesforce admin before any OAuth policy changes to avoid unexpected revocations.
- If your Salesforce org uses a short refresh token timeout, ask your admin to extend it in the Connected App settings under Policies > Refresh Token Policy.
Schema drift detected
Schema drift detected
Schema drift occurs when the structure of your CRM objects changes after you have configured field mappings. Salesforce field additions, removals, renames, or type changes can leave your mappings pointing to fields that no longer exist.
What you will see
- A warning alert banner reads “Schema drift detected.”
- Filtering the audit log by
schema.drift_detectedshows the event with metadata listing which fields changed and the old and new schema hash values. - Field mappings on the connection detail page show warnings for fields that are now missing or unmapped.
- Sync operations may fail with “field not found” or “invalid field” errors.
- The mapping completion rate shown in Integration Health drops.
Why this happens
- A Salesforce admin added, deleted, or renamed custom fields (those ending in
__c). - An installed managed package was updated, modifying object schemas.
- A custom object was deleted or replaced.
- Picklist field values were changed, causing validation failures on sync.
- Field-level security was changed, making previously accessible fields inaccessible to the integration user’s profile.
How to fix it
Click Refresh Schema on the connection detail page
This pulls the latest object metadata from Salesforce and updates the stored schema cache.
Review field mappings
After the refresh, check your field mappings for any marked as “unmapped” or showing a warning icon. These are mappings that reference fields that were removed or renamed.
Update or remove affected mappings
For each affected mapping, either select a replacement CRM field or mark the mapping as Ignored if you no longer need to sync that field.
Re-run AI suggestions if needed
If the schema changed significantly (many new or removed fields), click Suggest Mappings again to get fresh AI recommendations based on the updated schema.
How to prevent it
- PartnerOS automatically re-checks the schema every 24 hours, so minor drift is detected within a day. For planned admin changes, click Refresh Schema immediately after the changes are made rather than waiting.
- Monitor the mapping completion rate in Integration Health — a sudden drop indicates unmapped fields.
- Ask your Salesforce admin to notify you before making field changes on objects that PartnerOS syncs.
API rate limit exceeded
API rate limit exceeded
Salesforce enforces a rolling 24-hour API call limit. When PartnerOS or other connected apps consume too many calls, sync operations slow down or fail until the limit resets.
What you will see
- A warning alert banner reads “Rate limit low” when fewer than 10% of your daily API call allocation remains.
- Sync operations become slow or begin failing.
- In the audit log,
sync.pushandsync.pullevent metadata includesrateLimitRemainingandrateLimitTotalfields. A decliningrateLimitRemainingtrend confirms heavy consumption. - The API call count (24h) metric in Integration Health spikes.
Why this happens
- A large initial sync or re-sync of a big dataset consumes many API calls quickly.
- Other applications connected to the same Salesforce org share the same API call pool, reducing what is available to PartnerOS.
- Developer Edition orgs have a much lower limit (15,000 calls per day vs. hundreds of thousands for production orgs).
- Multiple PartnerOS connections to the same Salesforce org multiply call consumption.
How to check Salesforce’s side
In Salesforce, go to Setup > Company Information and look at API Requests, Last 24 Hours. This shows the total consumption across all connected apps. Compare this to PartnerOS’s audit log API call count to determine whether PartnerOS or another app is the primary consumer.How to fix it
Pause active syncs
Stop any in-progress backfill or manual sync operations to prevent further consumption while the limit is low.
Wait for the limit to reset
Salesforce API limits reset on a rolling 24-hour window. Monitor the
rateLimitRemaining field in audit log metadata to track recovery.Resume with reduced scope
When restarting, sync one object at a time rather than triggering all objects simultaneously. Start with the most critical objects (for example, Account and Contact) before others.
How to prevent it
- Keep an eye on the Integration Health dashboard — PartnerOS warns you when remaining calls drop below 10%.
- Schedule large backfill operations during off-peak hours when other apps are less active.
- If your org regularly hits limits, consider syncing fewer objects or reducing sync frequency, or work with your Salesforce admin to assess whether a higher-limit edition is needed.
Sync stuck or repeated failures
Sync stuck or repeated failures
When sync operations fail repeatedly without recovering, records in PartnerOS become stale and the “Last Sync” timestamp stops advancing. This is usually caused by data validation problems in Salesforce rejecting the records PartnerOS is trying to write.
What you will see
- The connection detail page shows a Last Sync date that has not advanced in an unexpectedly long time.
- The error count in Integration Health (7-day error trend) is rising.
- Filtering the audit log by
sync.pushorsync.pullreveals repeated failures with error messages in the metadata.
Why this happens
- A required field in Salesforce is not included in your field mappings, so PartnerOS is trying to create records that are missing required values.
- A lookup field references a parent record that does not exist in Salesforce (
INVALID_CROSS_REFERENCE_KEY). - A Salesforce validation rule is rejecting the data PartnerOS is pushing.
- A unique field constraint is violated because PartnerOS is attempting to create a record that already exists with the same value (
DUPLICATE_VALUE). - The integration user lacks create or edit permissions on certain objects or fields.
How to diagnose it
Check the audit log forsync.push or sync.pull events with errors. The error message in the metadata usually contains a Salesforce error code. Use this table to identify the cause:| Salesforce error code | What it means | Likely fix |
|---|---|---|
REQUIRED_FIELD_MISSING | A required field has no value | Add the required field to your field mappings, or set a default value in Salesforce |
INVALID_CROSS_REFERENCE_KEY | A lookup field references a non-existent record | Verify parent records exist before syncing child records; check lookup field mappings |
FIELD_CUSTOM_VALIDATION_EXCEPTION | A Salesforce validation rule is rejecting the data | Review the validation rule in Salesforce; adjust the mapped data or temporarily disable the rule |
DUPLICATE_VALUE | A unique field already has this value | Check for duplicate records or external ID conflicts |
ENTITY_IS_DELETED | The target record was deleted in Salesforce | The record no longer exists; the sync link can be removed |
How to fix it
Identify the error from the audit log
Filter by
sync.push or sync.pull events with errors. Note the Salesforce error code in the event metadata.Fix the underlying data issue
Based on the error code, update your field mappings (for example, add a missing required field), correct lookup references, or coordinate with your Salesforce admin to adjust validation rules.
Trigger a manual sync
After fixing the issue, click Trigger Sync on the connection detail page to retry.
How to prevent it
- Before running a large backfill, check the mapping completion rate in Integration Health. A low rate means required fields may be missing from your mappings.
- Test new mapping configurations with a small sync first to catch validation errors early.
- Use Suggest Mappings corrections to train the AI mapper on your organization’s field naming conventions, which reduces mismatches over time.
CDC subscription dropped (incremental sync stopped)
CDC subscription dropped (incremental sync stopped)
Change Data Capture enables near-real-time incremental sync from Salesforce. When the CDC subscription drops, new changes in Salesforce stop flowing into PartnerOS until the subscription is restored.
What you will see
- New records and changes in Salesforce are not appearing in PartnerOS, even though the connection shows Active.
- The audit log shows no recent
sync.pullevents for the affected connection — or the last one is older than expected. - Sync lag (average and p95) in the Integration Health dashboard has increased noticeably.
Why this happens
- CDC retention exceeded — Salesforce retains CDC events for only 3 days. If PartnerOS was disconnected or unable to process events for longer than that, those events are permanently lost and a full sync is needed to re-establish the baseline.
- CDC disabled in Salesforce — a Salesforce admin deselected your synced objects from Setup > Integrations > Change Data Capture.
- Token expired during subscription — if the OAuth token expired while CDC was active, the subscription may have dropped silently (without raising an obvious error).
- Salesforce maintenance — scheduled Salesforce maintenance windows can interrupt CDC subscriptions.
- Object not CDC-eligible — not all Salesforce objects support CDC; some require specific Salesforce editions.
How to diagnose it
- Check the audit log for
sync.pullevents. If the last event is older than a few minutes for an active CDC setup, the subscription has likely dropped. - In Salesforce, go to Setup > Integrations > Change Data Capture and confirm the affected objects (Account, Contact, Opportunity, Lead) are still selected.
- Check the connection status in Settings > Integrations — if it shows Reconnect required, resolve the token issue first (see Token revoked above).
- Check trust.salesforce.com for any active maintenance events affecting your Salesforce instance.
How to fix it
Resolve any token issues first
If the connection shows Reconnect required, reconnect the OAuth token before proceeding. A dropped token causes CDC subscriptions to fail silently.
Verify CDC objects in Salesforce
In Salesforce, go to Setup > Integrations > Change Data Capture. Confirm that Account, Contact, Opportunity, and Lead are all selected. Click Save if you need to re-enable any objects.
Trigger a full sync backfill
On the connection detail page in PartnerOS, click Trigger Sync. This runs a full backfill to re-establish the data baseline and catch any changes missed during the CDC gap.
Confirm incremental sync resumes
After the backfill completes, monitor the audit log for new
sync.pull events. They should start appearing within minutes as Salesforce CDC resumes sending change events.How to prevent it
- Monitor sync lag in Integration Health — a sustained increase in lag is the earliest indicator of a CDC problem, often before any alert fires.
- Keep OAuth tokens healthy. A dropped token is the most common silent cause of CDC subscription loss.
- Schedule a weekly full-sync reconciliation to catch any records missed during CDC gaps.
- Salesforce retains CDC events for 3 days — ensure PartnerOS syncs at least once within that window. If your org undergoes maintenance, run a manual sync once maintenance is complete.
- Ask your Salesforce admin to notify you before making changes to the CDC configuration.
Still having trouble?
If you have worked through the steps above and the integration is still not working, check the following:- Integration Health dashboard — review the 7-day error trend, API call count, and sync lag metrics for patterns that might point to a specific time or object type.
- Audit log — filter by connection and date range to find the exact event and error message. Copy the error message before contacting support.
- Salesforce setup — for Salesforce issues, ask your Salesforce admin to review the Connected App status, user profile permissions, and validation rules on synced objects.