# Troubleshooting

## Common Issues

### Sync Not Running

**Symptoms:** No records syncing via the feed

**Possible Causes:**

- The object's sync toggle is disabled in **Onboarded™ Setup → Data Operation Settings** and/or the object is not mapped in **Object Configuration**, for the objects you expect the feed to backstop (see [Feed vs. Webhook Scoping](#feed-vs-webhook-scoping))
- The org's initial data load hasn't completed yet — on a fresh install, initial population is performed by the Onboarded™ ETL (expected until that finishes; see [Initial Data Load](#initial-data-load))
- The scheduled job has been stopped for an extended period (deactivated user, removed CRON job)
- OAuth authentication not configured or expired
- Scheduled job not active
- Scheduling user lacks required permissions


**Resolution:**

1. In **Onboarded™ Setup → Data Operation Settings**, verify the sync toggle is enabled for each object you expect the feed to cover, and confirm the object is mapped in **Object Configuration**
2. Confirm the org's initial data load has completed (fresh installs are populated by the Onboarded™ ETL). If the scheduled job has been stopped for a long time and sync does not resume on its own, contact Onboarded™ support
3. Verify OAuth authentication is connected (check status in Integration Settings > Authenticate)
4. Check Apex Jobs for failed/aborted `OnboardedEventSyncQueueable` executions
5. Review `Onboarded_Error_Log__c` for specific errors
6. Verify the scheduling user has Onboarded™ Admin permission set


> **Note:** These symptoms apply to the scheduled feed. The real-time webhook is unaffected by any of the above — if webhook deliveries are also missing, see [Authentication Errors](#authentication-errors) and confirm the Webhook External Client App authorization from [API Authentication](#api-authentication).


### Authentication Errors

**Symptoms:** 401 Unauthorized errors in logs

**Resolution:**

1. Verify OAuth connection status shows "Connected" in Onboarded™ Setup
2. Try disconnecting and reconnecting to Onboarded™
3. Ensure your Client ID is correct
4. Contact Onboarded™ support if credentials are expired


### Records Not Linking

**Symptoms:** Lookup fields (Employee, Employer) are blank

**Resolution:**

1. In **Onboarded™ Setup → Data Operation Settings → Link References**, click **Run Links Now** and select the affected object to relink its existing records on demand (see [Run Links Now](#run-links-now-on-demand-per-object-linkage))
2. Verify parent records exist (Employers before Employees)
3. Check that Onboarded™ ID values match between related records


### Permission Errors

**Symptoms:** "Insufficient access" or "CRUD" errors in logs

**Resolution:**

1. Verify the integration user has Onboarded™ Admin permission set
2. Check that the scheduling user has access to all target objects
3. Verify field-level security allows access to all mapped fields
4. Review sharing rules if records are not being found


**Remember:** Operations run in USER_MODE and respect the running user's permissions.

### Governor Limit Errors

**Symptoms:** "Too many SOQL queries" or "CPU time limit exceeded"

**Resolution:**

1. Reduce batch size in Onboarded™ Setup (try 100 or 50)
2. Check for conflicting triggers on synced objects
3. Review automation (Flows, Process Builder) that may run during sync
4. Consider running sync during off-hours


### View Document Button Missing for Some Users

The View Document button respects the optional `documentViewCustomPermission` design property on the Employee Onboarded and Workflow Onboarded components. If the property is populated, only users with BOTH the Onboarded™ HR Representative permission set AND the named Custom Permission see the button. Also confirm PDF Storage is enabled (per the PDF Storage section) and that the task has a stored PDF.

### Employer Task Button Missing for Some Users

The Employer Task button respects the optional `employerTaskCustomPermission` design property. If set, users need BOTH the Onboarded™ HR Representative permission set AND the named Custom Permission. If unset, the button appears for any HR Rep or Admin.

### Unlock Task Modal Shows "No Form Sections"

The Unlock Task modal fetches form sections for the task at click time. If the task's form has not been parsed by Onboarded™ yet, the unlock options will not be available. Wait for the next sync to complete and try again, or escalate to Onboarded™ support if the issue persists.