School Data Sync Errors and Troubleshooting

Errors and remediation

The following table contains common errors that you may encounter after you enable sync for a sync profile in School Data Sync. The "Steps to remediate" column contains recommended steps for correcting the errors listed, often referencing the more detailed attribute validation steps listed in the Troubleshoot attribute mappings and values section of this article.

Error Entity Action Steps to remediate
AzureActiveDirectoryInvalidPropertyValue
Section
Add
The Section has an invalid mailNickname value and can't create the appropriate target object in Azure. Check the values for the section to ensure they contain only alpha numeric characters and no whitespace, as this value is used to create the smtp address of the O365 Group in Azure.
UnsynchronizableChange
Student
Add
Check if Source attribute matches Target attribute for this teacher. Steps for checking source and target listed in this article. Also, check to make sure the domain suffix setting in the sync profile is correct, and set to append the source attribute if that is required for the match to be completed successfully.
UnsynchronizableChange
Teacher
Add
Check if Source attribute matches Target attribute for this teacher. Steps for checking source and target listed in this article. Also, check to make sure the domain suffix setting in the sync profile is correct, and set to append the source attribute if that is required for the match to be completed successfully.
DuplicateTargetEntries
Student
Add
Two users exist with the same SIS ID in the source directory
InvalidLookupReference
SchoolStudents
Update
The student was unable to be added to the school. If the Student failed to sync or/add initially, this student will subsequently fail to add to the school. If this error occurs, check if the student has synced in the organization tab of the SDS portal. If not, remediate the sync/add error for the student. Also, confirm the School SIS ID is correct for this student, and if the school was in scope for sync.
InvalidLookupReference
SchoolTeachers
Update
The teacher was unable to be added to the school. If the teacher failed to sync/add initially, this teacher will subsequently fail to add to the school. If this error occurs, check if the teacher has synced in the organization tab of the SDS portal. If not, remediate the sync/add error for the teacher. Also, confirm the School SIS ID is correct for this teacher, and if the school was in scope for sync.
InvalidLookupReference
TeacherRoster
Update
The teacher was unable to be added to the section. If the teacher failed to sync/add initially, this teacher will subsequently fail to add to the section. If this error occurs, check if the teacher has synced in the organization tab of the SDS portal. If not, remediate the sync/add error for the teacher. Also, confirm the Section SIS ID is correct for this teacher, and if the section was in scope for sync.
InvalidLookupReference
StudentEnrollment
Update
The student was unable to be added to the section. If the student failed to sync/add initially, this teacher will subsequently fail to add to the section. If this error occurs, check if the student has synced in the organization tab of the SDS portal. If not, remediate the sync/add error for the student. Also, confirm the Section SIS ID is correct for this student, and if the section was in scope for sync.
None
Section
Add
Duplicate record exists or an invalid character exists in the name.
None
Student
Add
DisplayName for the student has invalid characters.
UnSpecified
Student
Update
The SIS ID of the student is invalid or is related to a student/user that did not successfully sync.
AzureActiveDirectory ObjectMissingDependantLicense (All one string, but broken here to make this table readable.)
Student Teacher
Add Update
This error can occur if SDS is attempting to assign a license to a user, but a dependent license is not currently assigned to the user. For example, the Classroom license requires the user must already have a license for Exchange Online and SharePoint Online. To address this, assign the dependent license, and re-run sync.
AzureActiveDirectoryNoAvailableLicenses
Student Teacher
Add Update
This error code can occur if SDS attempted to assign a license that is either expired or exhausted (All available licenses of this type have been assigned). To remediate, add more licenses of this type, to allow for additional assignments through SDS.
AzureActiveDirectoryInvalidLicense
Student Teacher
Add Update
This error occurs if SDS attempted to assign a license which is not present within the tenant. For example, if the tenant does not contain the Classroom Subscription and Licenses, but SDS attempts to assign Classroom Licenses to Teachers or Students, this error will be generated.
AzureActiveDirectoryReplicaUnavailable
School Section Student Teacher
Add Update
This error occurs is an AAD Graph Replica Server is unavailable. These errors are transient, and do not need any action from users. These errors will resolve themselves over time.
AzureActiveDirectory LastOwnerOfGroupCannotBeRemoved (All one string, but broken here to make this table readable.)
Teacher Roster
Delete
A teacher could not be removed from a class/group because a class/group must have at least one teacher.
AzureActiveDirectory RequestThrottledTemporarily (All one string, but broken here to make this table readable.)
This is a transient error that could occur due to throttling when processing a large amount of data. No action is required from user, and error should fix itself on a subsequent sync cycle.
UnmatchedEntry
Could not find a matching entry in Azure Active Directory for sync
AzureActiveDirectoryImmutablePropertyUpdateFailed
An attempt was made to update a property that cannot be updated. Please contact support
AzureActiveDirectoryInvalidUserPrinicipalNameFormat
UPN for the user is not in a valid format. Please check the source data and identity matching options
AzureActiveDirectoryInvalidUserUsageLocation
License Assignment failed for the user since the user does not have a Usage Location set. Please update the user from Office Admin Portal

Exporting errors and prioritizing remediation

When you encounter errors in School Data Sync, any errors associated with sync will be displayed on the sync profile summary page, after clicking on the Sync profile. The top errors will be displayed first, and will be actionable. We suggest you take action on these errors first. You can also view and export all sync errors associated with a given sync profile, for review and remediation purposes.

The steps below detail how to export errors for a given sync profile.

  1. Log into the SDS portal (sds.microsoft.com).
  2. Click on the sync profile you'd like to review errors for.
  3. Click the Download these Errors button to export the errors into a CSV file.
    errors-and-troubleshooting-1.png errors-and-troubleshooting-2.png
  4. Click ok when prompted.

Prioritizing errors for remediation

When troubleshooting errors in School Data Sync, it's always recommended that you prioritize Top Errors or ahead of troubleshooting any other error types in the All Errors view. This is because any instance of a Top Error may result in numerous subsequent errors for each instance, within the same sync profile. Often, remediating Top Errors will subsequently remediate many roster-related errors that also show in the all errors list, within the profile. This is the recommended method for remediating errors in bulk, in the most efficient manner possible.

Troubleshoot attribute mappings and values

When enabling Sync, students and teachers require a matching attribute between the source and target directories, in order to correlate the user objects between both directories. The instructions below contain the step by step instructions for checking the Source and Target attributes for students and teachers, detailed by sync method.

Check the source directory - CSV files

When configuring SDS sync with CSV files as the source directory, the three attributes listed below are available in the CSVs for matching the attribute of the user object in Azure AD.

  • Username Username is the header field in the Student and Teacher csv file, and can be formatted to match any of the available target directory options (UserPrincipalName, mailNickname, or Mail). To check the value of this attribute, check the student or teacher csv that contains the user.

  • Student Number/Teacher Number Student Number is the header field in the Student csv file, and Teacher Number is the header field in the Teacher csv file. The appropriate formatting for this attribute is a simple string of alpha numeric characters with no spaces, and it can provide a direct match to the mailNickname attribute of a user in Azure AD. You can also append this source attribute with a domain suffix,in order to match the UserPrincipalName or Mail attribute in Azure AD. To check the value of this attribute, check the student or teacher csv that contains the user.

  • Secondary Email Secondary Email is the header field in the Student or Teacher csv file, and can only be formatted to match the UserPrincipalName or Mail attribute in Azure AD. It requires the domain suffix be included in the value contained within the CSV file. To check the value of this attribute, check the student or teacher csv that contains the user.

Check the source directory - PowerSchool

When configuring SDS sync with PowerSchool as the source directory, the 3 attributes listed below are available in PowerSchool for matching the attribute of the user object in Azure AD.

Username This attribute in PowerSchool is called Student Username or Teacher Username. To check the value of this attribute for a student or teacher in PowerSchool, follow the steps below:

  1. Log into PowerSchool as an administrator.

  2. In the PowerSchool portal, select the Student tab for students or the Staff tab for teachers.

  3. Search for the user. Once found, click on the user.

  • If Student, in the left pane under the Information section, select Access Accounts. The Username for students in PowerSchool is called Student Username.

  • If Teacher, in the left pane under the Functions section, select Security Settings. The Username for teachers in PowerSchool is called Teacher Username.

Student Number/Teacher Number This attribute in PowerSchool is called Student Number for students, and ID for teachers. To check the value of this attribute for a student or teacher in PowerSchool, follow the steps below:

  1. Log into PowerSchool as an administrator.

  2. In the PowerSchool portal, select the Student tab for students or the Staff tab for teachers.

  3. Search for the user. Once found, click on the user.

  • If Student, the Student Number is displayed on the main search page before you click on the user. The Student Number in PowerSchool is called Student Number.

  • If Teacher, in the left pane under the Functions section, select Information. The Teacher Number in PowerSchool is called ID.

Secondary Email This attribute in Clever is called email for students and teachers. To check the value of this attribute for a student or teacher in Clever, follow the steps below:

  1. Log into PowerSchool as an administrator.

  2. In the PowerSchool portal, select the Student tab for students or the Staff tab for teachers.

  3. Search for the user. Once found, click on the user.

  • If Student, in the left pane under the Information section, select Student Email. The secondary Email for students in PowerSchool is called Email Address.

  • If Teacher, in the left pane under the Functions section, select Information. The secondary Email for teachers in PowerSchool is called Email Address.

Check the target directory - Azure AD

When configuring SDS sync, the target directory is always Azure Active Directory. The three attributes listed below are available for matching the attribute of the user object in source directory.

UserPrincipalName

Check UserPrincipalName through the Office 365 admin center

  1. Launch Internet Explorer in a Private Browser.

  2. Navigate to portal.office.com.

  3. Log into the Office 365 admin center with a Global Admin Account.

  4. Navigate to the Admin tile > Users tab > Active Users.

  5. Search for the user you want to check.

  6. Click on the user.

Note the UserPrincipalName listed in the Heading field.

Check UserPrincipalName through PowerShell

  1. Launch PowerShell as an Administrator with the Azure AD Module for PowerShell imported.

    Import-Module msonline
    
  2. Run the command below to connect to Azure AD. Enter Global Admin credentials when prompted.

    $Cred = Get-Credential
    Connect-MsolService -credential $cred
    
  3. Once connected, run the command below to check the UserPrincipalName of a single user. An example is shown where the user's name is Boyd Cowley.

    Get-MsolUser -SearchString "<Display Name>" | FL UserPrincipalName
    
Ex. Get-MsolUser -SearchString "Boyd Cowley" | FL UserPrincipalName


Note

The Search String parameter will search for the User you are looking for and only users with an email address or display name starting with this string will be returned. For more information about the Get-MsolUser cmdlet, see https://msdn.microsoft.com/en-us/library/dn194133.aspx.

Mail (primarysmtpaddress)

Check Mail (primarysmtpaddress) through the Office 365 admin center

  1. Launch Internet Explorer in a Private Browser.

  2. Navigate to portal.office.com.

  3. Log into the Office 365 admin center with a Global Admin Account.

  4. Navigate to the Admin tile > Users tab > Active Users.

  5. Search for the user you want to check.

  6. Click on the user.

  7. Select Edit Exchange Properties in the More Settings section.

  8. Select email address.

The mail attribute will be noted with a capital SMTP for the type, and also be listed in bold.

Check Mail (primarysmtpaddress) through PowerShell

  1. Launch PowerShell as an Administrator with the Azure AD Module for PowerShell imported.

    Import-Module msonline
    
  2. Run the command below to connect to Azure AD. Enter Global Admin credentials when prompted.

    $Cred = Get-Credential
    Connect-MsolService -credential $cred
    
  3. Once connected, run the command below to check the Mail attribute of a single user. An example is shown where the user's name is Boyd Cowley.

    Get-MsolUser -SearchString "<Display Name>" | FL proxyaddresses
    
    Ex. Get-MsolUser -SearchString "Boyd Cowley" | FL proxyaddresses
    
  4. Proxyaddresses is a multi-valued attribute, and may contain multiple entries. The address with a capital SMTP is the primarysmtpaddress for the user, and is the Mail attribute in Azure AD.

Note

The Search String parameter will search for the User you are looking for and only users with an email address or display name starting with this string will be returned. For more information about the Get-MsolUser cmdlet, see https://msdn.microsoft.com/en-us/library/dn194133.aspx.

mailNickname (Alias)

Check mailNickname (Alias) through the Office 365 admin center

  1. Launch Internet Explorer in a Private Browser.

  2. Navigate to portal.office.com.

  3. Log into the Office 365 admin center with a Global Admin Account.

  4. Navigate to the Admin tile > Users tab > Active Users.

  5. Search for the user you want to check.

  6. Click on the user.

  7. Select Edit Exchange Properties in the More Settings section.

  8. Select general.

The mailnickname (*Alias) attribute will be shown below displayname.

Check mailNickname (Alias) through PowerShell

  1. Launch PowerShell as an Administrator with the Azure AD Module for PowerShell imported.

    Import-Module msonline
    
  2. Run the command below to connect to Azure AD and Exchange Online. Enter Global Admin credentials when prompted.

    $Cred = Get-Credential
    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.outlook.com/powershell/ -Credential $Cred -Authentication Basic -AllowRedirection
    Import-PSSession $Session
    Connect-MsolService -credential $cred
    
  3. Once connected, run the command below to check the Mail attribute of a single user.

    Get-MsolUser -SearchString "<Display Name>" | FL proxyaddresses
    
  4. Proxyaddresses is a multi-valued attribute, and may contain multiple entries. The address with a capital SMTP is the primarysmtpaddress for the user, and is the Mail attribute in Azure AD.

  5. Run the line below to pull the alias value of the user

    Get-Recipient <primarysmtpaddress> | FL Alias
    

Note

The Search String parameter will search for the User you are looking for and only users with an email address or display name starting with this string will be returned. For more information about the Get-MsolUser cmdlet, see https://msdn.microsoft.com/en-us/library/dn194133.aspx.