> For the complete documentation index, see [llms.txt](https://docs.aohwv.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aohwv.dev/help-and-support/troubleshooting.md). # Troubleshooting Symptoms, likely causes, and steps to resolve the most common AOH Sync issues. If you work through these steps and the issue persists, contact support at ****. Include the error message, the Connector name, and when the issue started. *** ## Sync is not running **Symptoms:** The Dashboard shows no recent Sync activity; the last Sync timestamp is old; a scheduled Sync time has passed with no result. {% stepper %} {% step %} **Check whether the schedule is paused** Go to **Connectors** → your Connector → **Schedule**. If the schedule shows a paused state, resume it using the menu next to the schedule. {% endstep %} {% step %} **Check for a stuck Sync** AOH Sync will not start a new Sync while one is already running. Go to your Connector's **Sync History** and check whether a job has been running unusually long. If it appears stuck, you can cancel it and trigger a fresh Sync. {% endstep %} {% step %} **Verify the Connector is enabled** Go to **Connectors** → your Connector → **Settings** and confirm the Connector is active. {% endstep %} {% step %} **Contact support if none of the above resolves it** Email with the Connector name and the last known successful Sync time. {% endstep %} {% endstepper %} *** ## A new employee is not appearing in Entra ID **Symptoms:** A newly hired employee exists in the HR system but is not in Entra ID after the Sync has run. {% stepper %} {% step %} **Confirm the Sync has run since the employee was added to HR** Check the Connector's **Sync History** to see when the last Sync completed. If it has not run since the hire date, wait for the next scheduled Sync or trigger one manually. {% endstep %} {% step %} **Check for missing required fields** Open the Sync log and search for the employee's name or email. A skip entry will show the reason. The most common causes are a missing work email address, missing first or last name, or missing employee ID. Correct the missing data in your HR system and re-run the Sync. {% endstep %} {% step %} **Check the employee's start date** Some Connector configurations exclude employees whose start date is in the future. If the employee has a future start date, they may sync automatically when that date arrives. {% endstep %} {% step %} **Check Sync scope rules** Go to your Connector's **Settings** and review any scope filters. The employee's department, location, or employment type may be excluded from Sync. {% endstep %} {% endstepper %} *** ## Users are not updating in Entra ID after an HR change **Symptoms:** An employee changed departments, job titles, or managers in the HR system, but Entra ID still shows the old values. {% stepper %} {% step %} **Confirm the change has synced** Check the Connector's **Sync History** for a Sync run that occurred after the HR change. If no Sync has run, trigger one manually from the Connector view. {% endstep %} {% step %} **Check the Field Mapping for the changed attribute** Go to **Connectors** → your Connector → **Field Mappings** and confirm that the attribute you expect to update is mapped from the HR source to the Entra ID target. If the field is not mapped, changes to it will not sync. {% endstep %} {% step %} **Check for an exclusion on the individual user** In the **Identities** view, search for the employee. If they are marked as excluded from Sync, their record will not update. Remove the exclusion if it was applied in error. {% endstep %} {% endstepper %} *** ## Login issues **Symptom: Cannot log in — "Access Denied"** You have not been granted an AOH Sync role. Ask your AOH Sync Administrator to add you under **Administration** → **Access Management**. See [Access Management](/administration/access-management.md). **Symptom: Cannot log in — MFA prompt loops or fails** AOH Sync uses your organization's Entra ID for authentication, including any MFA policies your organization has configured. If MFA is failing, contact your internal IT team to verify your MFA method is working. **Symptom: Logged out unexpectedly** Sessions expire based on your organization's Entra ID session policy. Log in again. If you are being logged out unusually frequently, your Administrator can adjust the session lifetime in Entra ID conditional access settings. *** ## Connector shows connection errors **Symptom:** The Connector status shows a connection failure or the last Sync log shows an authentication error against the Source System. {% stepper %} {% step %} **Test the connection** Go to **Connectors** → your Connector → **Settings** and use the connection test option. This confirms whether AOH Sync can reach your HR system with the current credentials. {% endstep %} {% step %} **Check whether credentials have expired** HR system API keys and passwords expire. Go to **Administration** → **Vault** and verify the secret used by this Connector is current. Update it if the credential has rotated. See [Vault](/administration/vault.md). {% endstep %} {% step %} **Check that the HR system is accessible** Confirm the HR system is reachable from your environment. If your HR system recently changed its API endpoint or security settings, update the Connector configuration to match. {% endstep %} {% endstepper %} *** ## Sync errors in the log **Symptom:** The Sync History shows completed with errors; individual records show error codes. | Error | What it means | What to do | | ------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Invalid email format | The email address in HR is malformed (missing @, extra spaces, or invalid characters) | Correct the email in your HR system and re-sync | | Manager not found | The manager reference on the record does not match any identity in Entra ID | Verify the manager's email in HR, sync the manager first if they are also new | | Duplicate record detected | Two HR records have the same identifying field (employee ID or email) | Resolve the duplicate in your HR system | | Required field missing | Email, first name, last name, or employee ID is blank | Add the missing data in HR and re-sync | | Rate limit — will retry | Microsoft's directory service has temporarily throttled requests | No action needed; AOH Sync retries automatically | | Connection failed | AOH Sync could not reach the HR system or Entra ID | See "Connector shows connection errors" above | If you see an error not listed here, copy the exact error text and email it to . *** ## Entra ID groups are not updating **Symptom:** Users are not being added to or removed from expected Entra ID groups after a Sync. {% stepper %} {% step %} **Confirm group Sync is enabled** Go to your Connector's **Settings** and verify that group Sync is active. {% endstep %} {% step %} **Review the group membership rules** Go to **Connectors** → your Connector → [**Field Mappings**](/feature-reference/connectors/field-mappings.md) and confirm the rule criteria match the user's current HR attributes. If the user's department or job title does not match the rule, they will not be added to the group. {% endstep %} {% step %} **Check for manual overrides in Entra ID** Group memberships managed by AOH Sync should not be edited manually in Entra ID — the next Sync will overwrite manual changes. If a manual change was made and reverted by AOH Sync, update the rule instead. {% endstep %} {% endstepper %} *** ## Users unexpectedly removed from Entra ID **Symptom:** User accounts were disabled or deleted in Entra ID after a Sync ran. {% hint style="warning" %} If accounts were removed and you need to restore them, deleted Entra ID accounts can often be recovered from the Entra ID recycle bin within 30 days. {% endhint %} AOH Sync deprovisions accounts when the corresponding HR record is marked as terminated or when the record falls outside the configured Sync scope. Check whether: * The employee was marked terminated in your HR system (intentionally or in error). * A scope change in the Connector excluded a group of users that previously synced. * Your HR system returned an unexpectedly small dataset (an API error may have appeared as mass terminations — AOH Sync has a deletion threshold that limits how many accounts it will remove in a single Sync, and it should have flagged this). Contact support if you believe accounts were removed incorrectly and you need help with recovery. *** ## Related * [FAQ](/help-and-support/faq.md) * [Contact Support](/help-and-support/contact.md) * [Connector Sync History](/feature-reference/connectors/logs.md) * [Audit & Status Logs](/administration/audit-and-status-logs.md) * [Vault](/administration/vault.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.aohwv.dev/help-and-support/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.