> For the complete documentation index, see [llms.txt](https://docs.kernel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kernel.ai/integrations/salesforce-integration/troubleshoot-sync.md).

# Troubleshoot sync and check integration health

Diagnose missing links, failed field copies, missed Salesforce schedules and differences between Kernel, Salesforce and exports.

Start with the stage where the value stopped moving. A Kernel web app sync, a Salesforce Record Sync job, and an Account backfill have different run histories and checks.

### Before you start

Have the configuration name, the time of the attempted run, and one affected source record ready. Ask a Salesforce administrator to help if you cannot view jobs, logs, or field permissions.

Check the package version under **Setup → Installed Packages**. Version 3.12.5 added sync failure summaries, and version 3.13.0 added **Recent Job Runs** in **Sync Schedules**.

### Find the right run history

| What you ran                   | Where to start                                               | What to check                                                   |
| ------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------- |
| A sync from the Kernel web app | **CRM → Syncs → Monitor**                                    | Destination object, successes, errors, and record-level details |
| **Run Sync Now** in Salesforce | The result shown in **Record Sync**, then **View Apex Jobs** | Job ID, status, and any failure message                         |
| A scheduled Salesforce sync    | **Kernel Setup → Sync Schedules**                            | The scheduled job and **Recent Job Runs**                       |
| **Run Backfill**               | **Backfill Kernel Accounts → View Apex Jobs**                | Backfill status and whether the Account lookup was populated    |

Use **Kernel Application Logs** for the package's diagnostic entries. Match entries to the run time and job ID where available. The absence of a log entry alone does not confirm that a run succeeded or that a schedule executed.

**Recent Job Runs** shows the five most recent Record Sync batch jobs across manual and scheduled runs. Each configuration creates its own batch job. An older run may have left this list; use **Setup → Apex Jobs** to find it.

### A schedule has a next run but no recent execution

1. In **Sync Schedules**, record the job name, **State**, **Next Run**, and **Created By**.
2. In **Setup → Scheduled Jobs**, find the corresponding `KernelSync_…` job. Check its state and the user associated with the schedule. Confirm that the user is still active.
3. Check the scheduling user's Salesforce timezone against the intended hour. Salesforce interprets the schedule in that user's timezone. Use **Next Run** to check the actual next execution time.
4. In **Setup → Apex Jobs**, look for `KernelSyncBatchable` entries after the last successful run. Record the status and error details of any matching entry.
5. Compare these results with **Recent Job Runs** and the relevant **Kernel Application Logs** entries.
6. Record the installed package version and any recent upgrade date for your support request.

A future **Next Run** is the schedule's planned execution time. Verify an actual job entry and a target record update to confirm the copy ran.

If there is no job entry or the state does not explain the missed run, send the details to Kernel Support. Keep the job details before changing the schedule so the missed execution can be investigated.

### An Account link is missing

The standard directions use different lookups:

| Direction                 | Required target lookup                                                    |
| ------------------------- | ------------------------------------------------------------------------- |
| Account to Kernel Account | `Kernel_Account__c.Linked_Account_Field__c` identifies the source Account |
| Kernel Account to Account | `Account.Kernel_Account__c` identifies the source Kernel Account          |

1. Open the affected Account and its Kernel Account, and check both lookups.
2. Confirm the **Source Key Field** and **Target Key Field** in the sync configuration. The standard directions match Salesforce record IDs through these lookups.
3. Review object access, field access, and record access for the user performing the failed operation. Editing Account as an object and editing its **Kernel Account** lookup are separate checks.
4. If the Account's **Kernel Account** lookup is blank, have an administrator review and run [backfill](https://docs.kernel.ai/integrations/salesforce-integration/record-sync-backfill-and-schedules#link-existing-accounts).
5. Check the backfill result and both lookups before retrying the field copy.

Backfill selects blank Account lookups. If a lookup is populated with the wrong record, ask Kernel Support to review the relationship before changing it.

See [Installation](https://docs.kernel.ai/integrations/salesforce-integration/package-installation-guide) and the [integration user permission matrix](https://docs.kernel.ai/integrations/salesforce-integration/salesforce-integration-user-permission-matrix#link-and-sync-records) for the access required by each operation.

### The job finished, but a target field did not change

Check one affected record through the mapping:

1. Confirm the direction and destination object. A value written to Kernel Account appears on Account only when the relevant Account mapping also runs.
2. Check that the source field already contains the value you expected. Record Sync copies existing Salesforce values; it does not request fresh enrichment.
3. Confirm the mapping includes the intended target field.
4. Check that the source record meets the saved filter. The filter runs against the source object, so `Id` must be the source record's Salesforce ID.
5. Check the key fields and lookup on the matching target record.
6. Review the failure summary and the running user's access to the source and target fields and records.

If the value is missing on Kernel Account before the Salesforce copy starts, inspect the **CRM push** run in the Kernel web app first. For an automatic refresh, check whether Kernel has changed that account's values since the previous refresh.

If you use a fill-empty filter, check the target field and the lookup used in that condition. A populated target field can correctly exclude a source record. The filter controls every mapping in the configuration; it does not apply independently to each target field.

### The filter produces an error or selects no records

**Query Filter (Optional)** accepts the condition portion of a SOQL query. For example, use `Id = '<source record ID>'`. Do not include `SELECT`, `FROM`, or `WHERE`.

1. Confirm the source object and use field API names available from that object.
2. If the condition uses a related record, confirm the relationship path and both Account links.
3. Check the exact source record against every part of the condition, including blank-value checks.
4. Save the intended filter and inspect the next job's status and error details.

Do not remove a filter to bypass a query error. A blank filter can widen the next run to the whole source object. Keep the intended scope and correct the field name or condition.

### A value exceeds the target field's length

A `FIELD_VALUE_TOO_LONG` error means the source value is longer than the mapped target field accepts.

1. Identify the source and target objects and the exact field API names in the error.
2. In **Setup → Object Manager → Fields & Relationships**, open the field on each object and compare its type and length.
3. Check the source value. Confirm that it is the identifier or value the mapping is intended to copy.
4. Correct the mapping or review the target field definition with your Salesforce administrator, then retry the affected record.

For KERN IDs, distinguish `Kernel_Account__c.Kernel_ID__c` from `Account.Kern_Id__c`. They have the same label but are separate fields. Keep identifiers intact when resolving a length mismatch.

See [KERN ID fields](https://docs.kernel.ai/integrations/salesforce-integration/custom-object#kern-id-fields) for the package field definitions.

### Salesforce rejects a restricted picklist value

An `INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST` error means Salesforce rejected a value for the target picklist.

1. Record the exact value, field API name, destination object, and affected record from the error.
2. In **Setup → Object Manager → Fields & Relationships**, open the target field. Compare the incoming value with its active picklist values, including their API names.
3. If the object uses record types, check which values are available for the affected record's record type.
4. Have your Salesforce administrator confirm the intended classification, then update the allowed values or correct the field mapping.
5. Retry the affected record and check the destination value and run result.

For a CRM push, review the mapping in the Kernel web app. For a Record Sync copy, review the source and target fields in Salesforce. A field with the right label may still use a different set of accepted values.

### Values differ between Kernel, Salesforce, or an export

Compare one record and one field through the complete data route:

1. Match the Salesforce record ID and KERN ID across the views. Confirm that each value refers to the same company identity. Several CRM accounts can share a KERN ID, so the KERN ID alone does not identify the CRM record.
2. Check the entity level. For headcount and revenue, distinguish **Entity**, **Consolidated**, and **Recommended** values. Confirm which one your comparison or mapping uses.
3. Check the exact mapped field API names and objects. A value on Kernel Account and a value on Account are separate destinations, even when the field labels look alike.
4. Compare the source enrichment date where available, the CRM push run time and result, and the Record Sync run time and result. For an export, also record when the file was generated.
5. Follow the sequence. Check that the expected source value existed before the relevant run, that the record was included, and that the run completed without a failure for that record.

If the source value is correct but the destination is different, investigate the mapping, filter, and run between them. If an export and a current screen disagree, provide both values and their timestamps to Kernel Support. The cause needs to be checked against the specific record and data route.

### A summary reports failures without every record's details

Sync summaries include processed and failed record counts. Diagnostic entries can contain a sample of failures, so a summary is not necessarily a complete list of every failed record.

Check both the completion summary and any failure entries for the same job. For a run started in the Kernel web app, also open **Monitor** for record-level details and generated files.

If you still cannot identify the affected records, send Kernel Support:

* The Salesforce environment and installed package version
* The configuration name, source object, target object, and direction
* Whether you used the Kernel web app, **Run Sync Now**, a schedule, or **Run Backfill**
* The job ID, run time, and timezone
* The status, error text, and relevant log entries
* One affected record ID, the mapped field names, and the expected result

These details let the team trace the run and the point where it failed.