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 support@aohwv.dev. 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.
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.
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.
Verify the Connector is enabled
Go to Connectors → your Connector → Settings and confirm the Connector is active.
Contact support if none of the above resolves it
Email support@aohwv.dev with the Connector name and the last known successful Sync time.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Sync errors in the log
Symptom: The Sync History shows completed with errors; individual records show error codes.
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 support@aohwv.dev.
Entra ID groups are not updating
Symptom: Users are not being added to or removed from expected Entra ID groups after a Sync.
Confirm group Sync is enabled
Go to your Connector's Settings and verify that group Sync is active.
Review the group membership rules
Go to Connectors → your Connector → Field Mappings 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.
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.
Users unexpectedly removed from Entra ID
Symptom: User accounts were disabled or deleted in Entra ID after a Sync ran.
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.
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
Last updated