# Troubleshooting

## Common Issues

### Sync Not Running

**Symptoms:** No records syncing, timestamps not updating

**Possible Causes:**

- Sync toggles not enabled
- OAuth authentication not configured or expired
- Scheduled job not active
- Scheduling user lacks required permissions


**Resolution:**

1. Verify sync toggles are enabled in Onboarded™ Setup
2. Verify OAuth authentication is connected (check status in Integration Settings > Authenticate)
3. Check Apex Jobs for failed batch jobs
4. Review `Onboarded_Error_Log__c` for specific errors
5. Verify the scheduling user has Onboarded™ Admin permission set


### 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. Run link resolution: `OnboardedSyncScheduler.runLinkOnly();`
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 page) 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.

### I-9 Authorized Until Field Not Updating

This enrichment requires a Field Mapping for `authorized_until` on the Task object. Confirm both Object and Field are populated in `OnboardedMappings__c`, that the Task name contains "I-9" (case-insensitive), and check the Error Log for any failure entries.