An integration that worked quietly for months can start misbehaving without any obvious cause. Contacts vanish between systems, the same customer appears twice, or a field shows last week’s value. The trick to troubleshooting is to resist fixing the symptom you can see and instead trace the record’s path from one system to the other.

Describe the Problem Precisely

Vague reports such as “the sync is broken” are not actionable. Gather specifics:

• One or two example records, identified by a unique ID rather than a name.
• What was expected, and what actually happened.
• When it last worked, and what changed around that time.
• Whether it affects one record, a group of records, or everything.

The scope matters enormously. A single failing record usually points to its data. A whole category failing points to a rule or mapping. Everything failing points to connection, authentication or an outage.

Work Through a Layered Checklist

Start at the bottom and move up. Many hours get wasted debugging logic when the real problem is an expired credential.

1. Connection. Is the integration enabled and authorized? Have credentials, tokens or the integration user’s password expired or been changed?
2. Service status. Is either system reporting an incident or maintenance? Check the vendors’ status pages.
3. Limits. Has the integration hit usage or rate limits? Vendors set these and they vary, so consult current documentation.
4. Mapping. Were any fields renamed, deleted or changed in type, or picklist values altered, since the integration was set up?
5. Data. Does the failing record have missing required values, unusual characters or values that break validation?
6. Rules. Could a workflow, validation rule or another integration be blocking or overwriting the change?

Match the Symptom to Likely Causes

Symptom	Likely causes	First thing to check
Records never arrive	Filter excludes them, authentication failure, required field missing	Sync log for the record and any error message
Duplicates appear	Match key absent or inconsistent, two integrations creating records	How the record was matched or created
Values are stale	Scheduled sync paused, one-way flow overwritten, caching	Last successful sync time
Values flip back	Two-way sync conflict, another system overwriting	Which system owns the field
Whole sync stopped	Expired credentials, deactivated integration user, vendor change	Authorization status and alerts
Partial fields missing	Field-level permissions for the integration user	Permissions on the specific fields

Field-level permissions are an underrated cause. If the integration user cannot read or write a field, the sync may silently skip it rather than report an error.

Read the Logs Carefully

Most integration tools keep some record of attempts and failures. Look for the exact error text, the record involved and the time. Error messages often name the field or rule at fault. Copy them verbatim into your notes, since a precise message is far more useful when searching documentation or contacting support.

If logs are short-lived or absent, consider turning on more detailed logging temporarily, and set up a simple alert for failures going forward.

Fix, Then Repair the Data

Fixing the cause does not restore what was missed. After correcting the issue, identify the affected window and records. Depending on your tool, you may be able to resend failed records, or you may need to run a controlled backfill. Run a small batch first, confirm the outcome, then process the rest. When duplicates were created, merge them with a documented rule about which values survive, and confirm that the match key now prevents recurrence.

Reduce Future Incidents

Prevention is mostly routine. Use a dedicated integration account rather than a person’s login. Calendar the expiry date of any credential that expires. Announce field changes to the admin who owns integrations before they happen. Keep the mapping document current so you can see at a glance which integrations a change affects. A brief weekly glance at failure counts catches slow-burning issues before users do.

A Hypothetical Example

A support manager notices that new customers are not appearing in the CRM from the billing tool. The admin collects one missing customer’s billing ID and checks the sync log, finding repeated authorization errors starting on a specific day. The integration user’s password had been reset under a company-wide security policy. After updating the credential, new records flow again, but the gap period still has missing customers. The admin runs a small test resend, confirms the records match correctly by billing ID, then resends the rest. Finally, she moves the integration to a service account excluded from routine password resets and adds a failure alert.

Frequently Asked Questions

Why does a sync fail for only some records? Usually because those records have data that conflicts with the destination’s rules: missing required fields, invalid values or no match. Compare a failing and a working record side by side.

Is it safe to re-run a sync? It depends on how the tool handles matching. With reliable match keys it should update rather than duplicate, but test a small batch first.

How do I know which system is right when values differ? Refer to your system-of-record decision. If none exists, make one now and document it.

Should I contact vendor support? Yes, once you have an example record, exact error text and a timeline. Those details make support far faster.

Can a sync error cause data loss? It can if a faulty mapping overwrites or blanks fields. Keep backups or exports before large corrective operations.

Next Step

Check today whether your most important integration has a failure alert, a dedicated service account and a documented expiry date for its credentials. If any of the three is missing, fix that first.