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.

AzureActiveDirectoryObjectMissingDependantLicense

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.

Exporting errors and prioritizing remediation

When you encounter errors in School Data Sync, any errors associated with sync will be displayed on the right pane, after clicking on the Sync profile. The errors can be reviewed directly from this page. If you have a large number of errors however, it is easier to export the list of errors, in order to effectively report on and prioritize the remediation of the errors generated.

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 Show Errors option within the sync profile page.

    Screenshot of the Show Errors option on the sync profile page in School Data Sync.
  4. Click the Download Errors option after the errors list is displayed.

    Screenshot of the Download Errors option in the sync profile page in School Data Sync.
  5. Click the Refresh button on the browser to see if the download has completed.

  6. If the download has completed, you will see the File Ready for Download option after the page refreshes.

    Screenshot shows how, after the errors download has completed, the File Ready for Download option is visible after the  the sync profile page refreshes in School Data Sync.
  7. Click the available blue link to open and/or save the error report.

Prioritizing errors for remediation

When troubleshooting errors in School Data Sync, it's always recommended that you prioritize any student add errors or teacher add errors, ahead of troubleshooting any other error types. This is because any instance of a student or teacher failing to add/sync successfully can result in numerous subsequent errors for each instance of this user being added to schools and/or sections within the same sync profile. Often, remediating user add errors will also subsequently correct the roster-related errors that also show in 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 – Clever

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

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

  1. Log into Clever as a District Admin.

  2. In the Clever portal, navigate to Data > Browse in the left pane.

  3. Select the Students or Teacher tab and search for the user.

  4. Click on the student or teacher to display the detail view of the user.

  5. Clever Username is the first attribute listed.

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

  1. Log into Clever as a District Admin.

  2. In the Clever portal, navigate to Data > Browse in the left pane.

  3. Select the Students or Teacher tab and search for the user.

  4. Click on the student or teacher to display the detail view of the user.

  5. One of the last attributes listed is student_username or teacher_username.

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 Clever as a District Admin.

  2. In the Clever portal, navigate to Data > Browse in the left pane.

  3. Select the Students or Teacher tab and search for the user.

  4. Click on the student or teacher to display the detail view of the user.

  5. Email is one of the first attributes listed for teachers and students.

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 Clever is called Clever Username. 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 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 Student 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.

Share Facebook Facebook Twitter Twitter Email Email

Was this information helpful?

Great! Any other feedback?

How can we improve it?

Thank you for your feedback!

×