> ## Documentation Index
> Fetch the complete documentation index at: https://support.fieldko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose Rep Issues

> Find sync logs, errors, and device details in Salesforce, and fix the most common problems reps run into.

When a rep can't sync, is missing records, or doesn't see a change you made, FieldKo records the details you need in Salesforce. Use this page to find the problem by its symptom, fix it, and look up sync logs, errors, and device details.

## User Permissions Needed

| To do this | You need |
| - | - |
| View sync details and attendance | FieldKo Native Permission Set |

## Find the Problem by Symptom

Start with what the rep reports, and then go to the matching section.

| The Rep Reports | Go To |
| - | - |
| An error message when syncing or logging in, or sync never completes | [Rep Can't Sync at All](#rep-cant-sync-at-all) |
| No visits, or missing accounts or other records, with no error | [Rep Has No Visits, or Records Are Missing](#rep-has-no-visits-or-records-are-missing) |
| Issues in **Sync History**, or an edit that didn't reach Salesforce | [Records Fail to Upload](#records-fail-to-upload) |
| A setting, layout, or label you changed doesn't appear | [Rep Doesn't See a Change You Made](#rep-doesnt-see-a-change-you-made) |
| A side menu item or visit action is missing | [Menu Item or Action Missing](#menu-item-or-action-missing) |
| Background sync never runs | [Background Sync Never Runs](#background-sync-never-runs) |
| Photos don't appear in Salesforce | [Photos Missing in Salesforce](#photos-missing-in-salesforce) |

To investigate any of these, use the rep's [Sync Details](#sync-details), [Attendance](#attendance) records, or [data file](#data-files-from-reps).

## Common Problems

### Rep Can't Sync at All

| Message or Symptom | What It Means | What to Do |
| - | - | - |
| "Insufficient Privilege: User does not have access to FieldKo, Please contact your Manager or Administrator." | The rep doesn't have a FieldKo permission set. | Assign **FieldKo Representative Permission Set**, a Basic permission set, or a permission set group that contains one. |
| "No profile metadata found. Please contact to you administrator to generate it." | Page layouts haven't been collected for the rep's profile. | In the Metadata Collector, run **Collect Profiles Metadata**. See [Run the Metadata Collector](/admin/offline-data#run-the-metadata-collector). Check that the profile isn't in **Profiles To Exclude**. |
| First-time setup fails with "Network Required" on the office network. | Your network blocks `status.salesforce.com`. | Allow `status.salesforce.com` through your proxy or firewall. |
| The rep can't log in. | Connected app restrictions are blocking the rep, or the rep is using the wrong login host. | Check the permitted users and IP settings on the **FieldKo Native App** connected app. Give the rep your My Domain URL. |
| Sync fails with "Attempt to de-reference a null object". | The **Branding** custom setting record "Brands" doesn't exist. | Create the record. See the steps after this table. |

Create the missing Branding record in Setup:

1. From Setup, in the Quick Find box, enter `Custom Settings`, and then select **Custom Settings**.
2. Next to **Branding**, click **Manage**.
3. Create a record named `Brands`. Deselect **Enabled** unless you use brands.
4. Click **Save**.

### Rep Has No Visits, or Records Are Missing

No error appears for these problems. Check these items in order:

1. **Active call cycle.** The rep needs a call cycle with **Active** selected, their name as **Sales Representative**, and dates that cover today. Without one, no visits, tasks, or orders sync. See [The Date Window and Call Cycles](/admin/offline-data#the-date-window-and-call-cycles).
2. **Account scope.** The rep must own the account or be on its account team. In public group mode, the account must be shared with the rep's group. See [Accounts in Scope](/admin/offline-data#accounts-in-scope).
3. **Visit fields.** The visit's **Sales Representative** must be the rep, and its planned dates must be inside the sync window.
4. **Access.** The rep needs read access to the object and its fields.
5. **Metadata.** The object must be collected. Check that an **Object Metadata** record exists for it. If it doesn't, re-run the [Metadata Collector](/admin/offline-data#run-the-metadata-collector).
6. **Sync.** After you fix the problem, ask the rep to tap **Sync**, or **Reset Sync** if you changed layouts or objects.

### Records Fail to Upload

Open the rep's latest **Error Information** record in [Sync Details](#sync-details), or ask the rep for a screenshot of **Sync History** > **ISSUES** > **Show Details**.

| Message | What It Means | What to Do |
| - | - | - |
| "Insufficient privileges, you do not have create access" (or edit, delete) | The rep is missing an object permission. | Grant the permission. |
| `REQUIRED_FIELD_MISSING` | A required field is empty. | Ask the rep to fill in the field, or relax the requirement. |
| `FIELD_CUSTOM_VALIDATION_EXCEPTION` | A validation rule fired. | Ask the rep to correct the record, or adjust the rule for mobile users. |
| "Sorry! No Call Cycle available. Please Contact your Manager or Administrator" | The visit's date isn't in an active call cycle. | Create or activate a call cycle. |
| "No parent record found, update the records and sync again." | A related record created offline didn't upload first. | Ask the rep to sync again. If the message keeps appearing, ask the rep to [send their data file to support](/troubleshooting/send-data-to-support). |
| "Cyclic Referencing, remove it and sync again." | Records created offline reference each other. | Ask the rep to [send their data file to support](/troubleshooting/send-data-to-support). |

If a rep says an edit didn't save, check field-level security. The app skips fields the rep can't edit when it uploads, without showing a message. The change can look like it synced but not reach Salesforce.

### Rep Doesn't See a Change You Made

| You Changed | What to Do |
| - | - |
| A custom setting | The rep syncs (any kind of sync). |
| A custom label | The rep taps **Sync** on the Sync screen. |
| A layout, field, record type, or Objects To be Fetched | You re-run the Metadata Collector, and then the rep runs **Reset Sync**. |

### Menu Item or Action Missing

Check the [Menu Configuration](/admin/configuration-reference#side-menu) and [Visit Actions Configuration](/admin/configuration-reference#visit-actions) custom settings. After a record exists, a blank field hides that item. Some visit actions appear only while the rep is checked in.

### Background Sync Never Runs

Check these settings in order:

1. In Setup, check that a **Sync Configurations** custom setting record exists. If there's no record, the app turns background sync off.
2. In that record, check **Enable Background Sync**, **Interval for Background Sync**, and **Background Sync within Business Hours**. See [Sync](/admin/configuration-reference#sync).
3. On the rep's device, check the app's **WiFi Only** setting. When it's on, background sync doesn't run on mobile data.

### Photos Missing in Salesforce

Reps must sync with **Sync Images** turned on. Background sync doesn't upload photos. A photo uploads only after its record has synced. To know whether to look in Files or Attachments, check **Enable File** in the **File Configurations** custom setting.

## Sync Details

Every sync a rep runs creates a **Sync Detail** record. To view them, from the App Launcher, find and select **Sync Details**. The **All** list view shows every record.

| Field | What It Means |
| - | - |
| Sales Representative | Who synced |
| Sync Action | **Login** (first-time setup), **Sync** (manual), **Reset**, or **BG\_Sync** (background) |
| Sync Status | **Started**, **Success**, **Failed**, or **Partial Sync** |
| Sync Start / End DateTime | When the sync ran |
| Previous Successful Sync | The rep's last successful sync before this one |
| UnSynced Data on Device | A summary of changes still waiting on the device |
| Device Key / Device Model / OS version | The device |
| Data 1 / Data 2 | Error details, as JSON |

Sync Detail records use these record types:

* **Sync State:** One record per sync.
* **Error Information:** Created when records fail to save during sync (status **Partial Sync**). **Data 1** lists each failed record with its error message, status code, fields, and IDs.
* **Transaction State:** Temporary records that prevent duplicates if a sync is interrupted. FieldKo deletes them at the end of each sync.

FieldKo keeps the latest 5 successful, 30 failed, 30 partial, and 10 started records per rep and device, and deletes older ones automatically.

<Tip>
  If a rep has **Started** records but no **Success**, the cause is usually a connection problem or a record that's blocking the sync. Open the newest **Error Information** record and read **Data 1**.
</Tip>

FieldKo doesn't include a report type for Sync Details. To build reports, create a custom report type on Sync Detail.

<Warning>
  Data 1 and Data 2 can contain record data, and all internal users can read the Sync Detail object by default. If that's a concern, restrict its sharing.
</Warning>

## Attendance

Each rep gets one **Attendance** record per day. It shows login and logout times, locations, the device, the app version (the **Mobile App Version** field), and any **Error Details**. See [Attendance](/managers/monitor-your-team#attendance).

## Data Files from Reps

Reps can email a full export of their device data (`allFieldKoData.json`) to [**support@fieldko.com**](mailto:support@fieldko.com) from **Sync** > **Data Recovery**. See [Send Your Data to FieldKo Support](/troubleshooting/send-data-to-support).

The file includes the records waiting to upload, background sync errors, recent sync results and issues, and the photos and files waiting to upload.

<Warning>
  Data files contain customer data. Store and delete them according to your data-handling policy.
</Warning>

If FieldKo Support needs to see the problem in your org, also [grant login access](#grant-fieldko-support-login-access).

## Grant FieldKo Support Login Access

Some problems appear only in the org where they happen. When you grant login access, FieldKo Support can log in as that user and see what the user sees, in a production org or a sandbox. You choose how long access lasts.

Login access is granted from the account that has the problem. If a rep sees the problem, ask the rep to follow these steps. If you see it, grant access from your own account. Work in the org where the problem happens:

1. In Salesforce, click your profile picture, and then click **Settings**.
2. In the Quick Find box, enter `Grant`, and then select **Grant Account Login Access**.
3. In the row for FieldKo Support, select an **Access Duration**.
4. Click **Save**.

Then email [support@fieldko.com](mailto:support@fieldko.com). Say which org has the problem (production or sandbox), give the user's username, and describe what happens. If a rep is affected, ask them to [send their data file](/troubleshooting/send-data-to-support) too. If FieldKo Support isn't listed on the **Grant Account Login Access** page, say so in your email.

For more about login access, see [Grant Login Access](https://help.salesforce.com/s/articleView?id=sf.granting_login_access.htm\&type=5) in Salesforce Help.

## App Version

To see what each rep is running, check the **Mobile App Version** on Attendance records and the **OS version** and **Device Model** on Sync Details. Menu Configuration can override the version label in the app's menu, so rely on these records instead.

## See Also

* [Troubleshooting: Start Here](/troubleshooting/start-here)
* [Fix Sync Errors](/troubleshooting/sync-errors)
* [Control What Syncs to the App](/admin/offline-data)
* [Configuration Reference](/admin/configuration-reference)
* [Track Your Team's Performance](/managers/monitor-your-team)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.