#iSyncSF Troubleshooting Guide

This guide walks you through the most common issues encountered when using iSyncSF, with structured diagnostic steps and resolution strategies for each scenario.

#Before You Start Troubleshooting

Before diving into a specific issue, gather the following information:

Check the Application Logs

Navigate to the Application Logs tab in iSyncSF. These logs capture operational errors such as connection failures, batch crashes, and unexpected exceptions. Filter by the template or job in question to narrow results.

Check the DataSyncAuditLog

The DataSyncAuditLog is the most important diagnostic object. Each record represents a single source record processed during a sync job. Filter by HasError = true to find all records that failed, and review the ErrorMessage field for Salesforce-level error details.

Verify the Sync Job Status

Open the sync job record and check the Status field. Common statuses include:

• Scan In Progress — The pre-scan phase is running.
• Scanned — Scan completed successfully; ready for execution.
• Sync In Progress — Records are being transferred to the target org.
• Synced — The sync completed.
• Aborted — The job was cancelled or crashed.
• Paused — The job is waiting for the scheduler to resume it.

Set the Log Level

For detailed diagnostics, set the DebugLevel system property to DEBUG or FINEST before reproducing the issue. The default level is ERROR, which only captures errors. After troubleshooting, reset to ERROR to reduce log volume. See the System Configuration Reference for instructions.

#Scan or Preview Not Starting

Symptom: The sync job status remains at "Scan In Progress" for an extended period with no visible progress, or the scan never transitions to "Scanned."

What to Check

1. Are there other batch jobs running? Salesforce allows a maximum of five concurrent batch jobs. If all five slots are occupied by other processes, the iSyncSF scan batch sits in the holding queue. Wait for other batches to finish, or abort unnecessary batch jobs from Salesforce Setup > Apex Jobs.
2. Check the child job statuses. Open the sync job record and review its related child job records. If all child jobs show "Completed" or "Queued" but the master job is still "Scan In Progress," the batch chain may have been interrupted between steps.
3. Is the Preview Batch Size too large? A high PreviewBatchSize on the template causes the scan to process too many records per batch iteration, potentially exhausting governor limits. Reduce it to 50 or lower and re-run the scan.
4. Deep self-referencing hierarchies. Objects with deep parent-child hierarchies referencing themselves (such as Account > ParentId) can cause the hierarchy computation to fail. If you suspect this, enable the UseKahnsAlgorithm system property (set it to true) to switch to an iterative hierarchy computation that handles deep hierarchies safely.
5. MaxInternalBatches too low. The scan engine processes records in internal iterations. If the MaxInternalBatches system property is too low, the scan may exit before completing all phases. Increase it (for example, from 50 to 200).

Resolution

• If the job is truly stuck (no running batch job corresponds to it), update the job status to "Aborted" and initiate a fresh scan from the UI.
• Reduce PreviewBatchSize on the template.
• Increase MaxInternalBatches in System Properties.
• Enable UseKahnsAlgorithm for deep hierarchies.

#Sync Running but Records Not Appearing in Target

Symptom: The sync job completes with status "Synced," but some or all expected records are missing from the target org.

What to Check

1. Review the DataSyncAuditLog status codes. Each audit log record has a StatusCode that tells you exactly what happened to that record:
   • 7 (Inserted) — Record was successfully created in the target. If it is not visible, it may be hidden by sharing rules. Verify the Destination_Record_ID field and search for it directly in the target org.
   • 2 (Updated) — Record was matched and updated in the target.
   • 4 (Existing) — Record was matched but intentionally skipped because UpdateExistingRecords is set to false on the Object Settings. Enable this setting if you want updates.
   • 5 (Source N/A) — The source record was deleted or became inaccessible between the scan and sync phases.
   • 1 (Insert Error) or 3 (Update Error) — The record failed. Check the ErrorMessage field for the specific Salesforce error.
2. Check the template line filter. Review the SOQL WHERE clause on the template line. A restrictive filter may exclude the records you expect to see.
3. Delta Sync date filter. If Delta Sync (ContinuousSync) is enabled, only records modified after the Last Sync Date are included. If the Last Sync Date is set ahead of the records' modification dates, those records will be excluded. Clear the Last Sync Date on the template to force a full re-sync.
4. Parent-child ordering. Ensure parent objects have lower Sequence numbers than child objects in the template lines. If a child is synced before its parent, the child's lookup field will not resolve and the record will fail.
5. Sharing and field-level security. The running user must have access to the source records. If OWD for the object is Private, consider enabling the OverrideRecordSharing option.

Resolution

• Adjust the template line WHERE clause to include the missing records, then re-scan.
• Clear the Last Sync Date for a full re-sync.
• Enable UpdateExistingRecords on the Object Settings if matched records should be updated.
• Fix the template line Sequence ordering so parents sync before children.
• Use the Retry function on the Execute tab to reprocess only failed records without re-running the entire job.

#Validation Rule and Automation Failures

Symptom: Records fail with errors such as FIELD_CUSTOM_VALIDATION_EXCEPTION, REQUIRED_FIELD_MISSING, or CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY (trigger errors).

What to Check

1. Identify the failing validation rule. The ErrorMessage in the DataSyncAuditLog contains the validation rule's error text. Use this to locate the specific rule in the target org.
2. Required fields missing. If the error is REQUIRED_FIELD_MISSING, a field required in the target org is either null in the source data or not mapped. Add an Object Field Mapping with an Expression to supply a default value.
3. Trigger errors. If target org triggers are causing failures, use Automation Control to disable them before syncing.
4. Duplicate rules. DUPLICATES_DETECTED fires when a Duplicate Rule matches the incoming record. Set a CustomExternalID on Object Settings to use upsert instead of insert, which bypasses duplicate rule evaluation on inserts.

Resolution

• Use Automation Control to disable validation rules, triggers, flows, and workflow rules in the target org before syncing. Re-enable them after the sync completes.
• Add Object Field Mappings with default expressions for required fields that are null in the source.
• Enable ContinueOnError on the template so that individual record failures do not abort the entire job.
• Use the Retry function to reprocess failed records after fixing the root cause.

#OAuth and Connection Errors

Symptom: Target org connection fails. The Org Master record shows "Token Expired," "Not Connected," or "Error" status. Sync jobs fail with callout errors.

What to Check

1. Check the Org Master record. Open the Org Master record for the target org. The OAuthStatus field shows the current connection state. The OAuthLastError field shows the most recent error message.
   • "Token Expired" — The access token expired and the refresh failed. The most common cause is a revoked refresh token (the Connected App was modified, or the admin revoked all tokens).
   • "Not Connected" — The org was never connected or was intentionally disconnected. Initiate the OAuth flow from the Org Connection page.
   • "invalid_grant" in the error message — The refresh token is no longer valid. You must re-authorize by disconnecting and reconnecting the org.
2. Is the OAuth Token Refresh scheduled job running? iSyncSF includes an hourly scheduled job that proactively refreshes tokens before they expire. If this job is not scheduled, tokens will expire after approximately two hours. Check the Scheduled Jobs tab in the Setup Assistant and ensure the OAuth Token Refresh job is active.
3. Remote Site Settings. Verify that the target org's instance URL is registered as a Remote Site Setting in Salesforce Setup. iSyncSF attempts to create these automatically, but the auto-creation can fail silently.
4. Callback URL mismatch. If the OAuth authorization flow itself fails, verify that the callback URL configured in the Connected App matches the one stored in iSyncSF's system configuration.
5. Connected App scopes. Ensure the Connected App includes the api, refresh_token, and offline_access scopes. Without refresh_token, no refresh token is issued and the connection expires permanently after the initial access token times out.

Resolution

• Disconnect the org from the Org Connection page and re-authorize.
• Ensure the OAuth Token Refresh scheduled job is active via the Setup Assistant.
• Verify or manually create Remote Site Settings for the target org's instance URL.
• Check that the Connected App on the target org includes the correct scopes and callback URL.

#Performance and Governor Limit Issues

Symptom: Sync jobs take significantly longer than expected, or you see errors related to SOQL query limits, CPU time limits, or callout size limits.

What to Check

1. MaxBatchSize too high. The MaxBatchSize on Object Settings controls how many records are sent per callout to the target org. A value above 200 with objects that have many fields can generate payloads that exceed Salesforce's 12 MB callout limit (System.CalloutException: Exceeded max size limit). Reduce it to 50–100 for objects with large numbers of fields or rich text fields.
2. ExternalMaxbatch on the template. This setting controls the total number of records sent per callout cycle. Reduce it if you see callout size errors.
3. Too Many SOQL Queries (101). This typically happens when relationship resolution runs per-record rather than in bulk. iSyncSF handles this automatically during the pre-scan, but a very high batch size can push the query count over the limit. Reduce MaxBatchSize.
4. Concurrent sync jobs. iSyncSF allows up to five sync jobs running simultaneously. Each job competes for batch execution slots and API limits. If performance is critical, run fewer concurrent jobs.
5. Target org automation overhead. Validation rules, triggers, and flows on the target org execute for every record inserted or updated. This slows down the sync and can cause timeout errors. Use Automation Control to disable target automations during bulk syncs.
6. Deep self-referencing hierarchies. Objects with deep parent-child self-references (10+ levels) cause expensive hierarchy computation. Enable UseKahnsAlgorithm for better performance.
7. MaxLimitUsage threshold. The MaxLimitUsage setting (default 80%) controls how much of the governor limit budget the engine uses before pausing. If set too low (for example, 50%), the engine pauses frequently, adding overhead from batch restarts. If set too high (above 90%), you risk governor limit exceptions.

Resolution

• Reduce MaxBatchSize on Object Settings to 50–100.
• Reduce ExternalMaxbatch on the template.
• Enable FAST processing mode via the SyncMode system property for faster data transfer.
• Use Automation Control to disable target org automations during sync.
• Enable UseKahnsAlgorithm for deep hierarchies.
• Schedule syncs during off-peak hours to avoid resource contention.

#Rollback Not Working

Symptom: Rollback does not delete records from the target org, does not restore original values, or gets stuck at "Rollback Started."

What to Check

1. Were records inserted or only updated? Rollback in delete mode only processes records with status code 7 (Inserted). If all synced records were updates (status code 2), rollback has nothing to delete. To restore updated records to their pre-sync values, Data Versioning must have been enabled before the sync ran.
2. Rollback permission. The user needs the TemplateRollbackSync custom permission to initiate a rollback. Check the permission assignment.
3. OAuth token validity. Rollback makes callouts to the target org to delete records. If the OAuth token has expired, the rollback will fail silently. Refresh the connection and retry.
4. Target org permissions. The integration user on the target org must have delete permission on the affected objects. Without delete access, the rollback scripts fail.
5. Stuck rollback batch. If the job is stuck at "Rollback Started," check Salesforce Setup > Apex Jobs for the rollback batch job status. If it failed, reset the job status back to "Synced" and re-initiate the rollback.
6. Data Versioning not enabled. If you expected rollback to restore updated field values and it did not, verify that the EnableVersion system property was set to true before the sync was executed. Versioning only captures snapshots during the sync if it is enabled at that time.

Resolution

• Refresh the OAuth token and retry the rollback.
• Enable EnableVersion in System Properties for future syncs so that updated records can be restored.
• Grant delete permissions to the integration user on the target org.
• If the rollback batch is stuck, reset the job status and re-initiate.
• For manual cleanup, use the Destination_Record_ID values from the audit logs to identify and delete records directly in the target org.

#Reading the DataSyncAuditLog

The DataSyncAuditLog is iSyncSF's central diagnostic object. Understanding its fields is essential for troubleshooting any sync issue.

Key Fields

Status Codes Reference

How to Filter Audit Logs

From the sync job record, navigate to the related DataSyncAuditLog list. Use these filter strategies:

• All errors: Filter by HasError = true.
• Errors by object: Filter by HasError = true and SObjectType = [ObjectName].
• Successful inserts: Filter by StatusCode = 7.
• Skipped records: Filter by StatusCode = 4 to find matched but skipped records.

For additional troubleshooting patterns, see the FAQ for answers to specific error codes.