Google School Directory Sync
Use this information to help solve issues with School Directory Sync (SDS).
Setup and configuration | Errors | Troubleshooting tools
Setup and configuration
Which ports and URLs do I need for SDSNote: This information can change over time. For the latest information, check for SDS updates.
SDS currently accesses the following URLs:
SDS currently accesses the following URLs:
| Topic | URL | Port |
|---|---|---|
| Authentication | https://www.google.com | 443 |
| All Feeds | https://www.googleapis.com | 443 |
| Certificate Revocation List Processing | http://www.gstatic.com/GoogleInternetAuthority/GoogleInternetAuthority.crl | 80 |
| Certificate Authority | http://crl.verisign.net | 80 |
For details on current CRLs, go to CRL check.
You need a server capable of sending mail to run a simulated sync. If you’re running SDS on a mail server, use the IP address 127.0.0.1. Otherwise, contact your mail administrator for the correct mail information.
When SDS connects to APIs (over HTTPS), it validates Secure Sockets Layer (SSL) certificates by connecting via HTTP to certificate revocation list (CRL) providers. Sometimes, these validations fail, usually due to a proxy or firewall blocking the HTTP request.
If SDS is unable to connect to the CRL providers, you might see the following error in your log file:
PKIX path validation failed: java.security.cert.CertPathValidatorException: revocation status check failed: no CRL found
For an up-to-date list of Google IP addresses, run a DNS TXT lookup of the subdomain _netblocks.google.com.
SDS can use a proxy server but can't respond to password challenges. Change your network setup to allow SDS to connect without a password challenge or without a proxy server.
SDS stores the SMTP password and OAuth token using a 2-way encryption scheme. This method protects your sensitive information from casual snooping or reverse engineering.
Errors
Error messagesIf errors occur while running a sync, they're captured in a log file.
| Error message | What it means | What to do |
|---|---|---|
| Column [...] doesn't exist or is empty on row number [...] | A required column is not in the CSV file. | Make sure your CSV file has the required columns. For details, go to Create CSV files. |
| Could not set attribute values for a group of type [...]. Skipping it. | There was a problem setting values of some attributes for the given group, such as name, email address, or description. You get an error when any of the fields that are used to set the attribute value are empty or missing. | Make sure to set the values for group attributes. |
| Could not set attribute values for an org unit of type [...]. Skipping it. | There was a problem setting values of some attributes for the given organizational unit, such as name or description. You get an error when any of the fields that are used to set the attribute value are empty or missing. | Make sure to set the values for organizational unit attributes. |
| Duplicate member [...] found for group [...]. Skipping it. | The group member already appears as a member of the group. The sync ignored every other occurrence of the same member. | Remove duplicate members from the group. |
| Duplicate owner [...] found for group [...]. Skipping it. | This group owner already appears as an owner of the group. The process ignores every other occurrence of the same owner. | Remove duplicate owners from the group. |
| Duplicate value found for column(s) [...] on row number [...] | A column that can only have unique values has a duplicate value. | Remove or change the repeated value. |
| Excluding Duplicate occurrence of group [...] | The same group email address is already used for a group. The sync ignored every other group with the same email address. | Change the email address of the group in question. |
| Excluding duplicate occurrence of org unit [...] | The organizational unit name is already in use. The sync ignored every other organizational unit with the same name. | Change the name of the duplicate organizational unit. |
| Excluding duplicate occurrence of user | User appears more than once in the CSV file. | Remove duplicate users from the CSV file. |
| Group mail [...] contains non-ASCII characters or is not properly formatted, and the group has been skipped. | The group's email address contains invalid characters or is not properly formatted. |
Make sure that the group's email address follows the guidelines for email addresses. Email addresses can be up to 63 characters long. This limit doesn't include the domain portion of the address, such as @yourschool.edu. Some words are reserved and can't be used as email addresses. View reserved words. |
| Group member [...] excluded from group [...], as it contains characters not allowed in a username | The group member's email address contains invalid characters. |
Make sure that the group's email address follows the guidelines for email addresses. Email addresses can have up to 63 characters. This limit doesn't include the domain portion of the address, such as @yourschool.edu. Some words are reserved and can't be used as email addresses. View reserved words. |
| Initialization failed for [...]. Skipping it. | Initialization of a user failed. | Contact Google Cloud Support to investigate. For details, go to Contact Google Workspace support. |
| Not adding staff as owner for group [...] as the staff ID is empty. | The staff ID for the group is empty so the group won't have staff added as an owner. The domain's admins can still manage the group. | Specify a staff ID for the group. |
| Org unit member [...] excluded from org unit [...], as it contains characters not allowed in a username | The organizational unit member's email address contains invalid characters. |
Make sure that the email address follows the guidelines for email addresses. Email addresses can have up to 63 characters. This limit doesn't include the domain portion of the address, such as @yourschool.edu. Some words are reserved and can't be used as email addresses. View reserved words. |
| Permission denied. Please verify that the user set as the owner of the class actually exists. | You removed the primary teacher of a class from the enrollment file. | Transfer the class to another primary teacher. |
| Quota exceeded. | The request rate limit exceeds the Classroom API quota limit. | See Classroom API Usage Limits. |
| Skipping non org unit result (no org unit name specified). | Organizational unit can’t sync to Google Workspace because it doesn't have a name. | Specify a name for every organizational unit. |
| Skipping non-group result (no group email specified). | The group's email address wasn't specified in the data. | Make sure there's an email address defined for every group. |
| Skipping non-user result (no username specified). | A user can’t sync to Google Workspace because a username isn't specified for them. | Specify a username for every user in the CSV file. |
| The course is not in a state that allows modification of its properties. | You tried to archive a course that a teacher previously deleted. | Change your class-deletion policy to avoid archiving courses. |
| There has been an error processing “Classes”. | Your classes.csv file includes a class that's associated with a course not found in the courses.csv. | Remove course mappings from your classes.csv file. Or, make sure your CSV files have a courses.csv file that includes all courses. |
| Username [...] contains non-ASCII characters or is not properly formatted, and the user has been skipped. | The user's email address contains invalid characters or is not properly formatted. |
Make sure that the user’s email address follows the guidelines for email addresses. Email addresses can have up to 63 characters. This limit doesn't include the domain portion of the address, such as @yourschool.edu. Some words are reserved and can't be used as email addresses. View reserved words. |
| You are not authorized to access this API. | You don't have permission to run SDS. |
Confirm that you're using Education or Nonprofits edition, which includes government agencies. Enable APIs for Classroom and your Google Workspace domain. For details, see Education edition requirements. |
If you're seeing memory-related errors, you need to increase the heap size for Java Virtual Machine. Increase the heap size by editing the
sync-cmd.vmoptions and config-manager.vmoptions files in the installation directory of SDS. The relevant entries look like this:-Xmx1000m(the maximum amount of memory for the heap size)-Xms64m(the minimum amount of memory for the heap size)
Edit both the
sync-cmd.vmoptions and config-manager.vmoptions files so that the change applies to both sync-cmd and Configuration Manager versions.Edit the -Xmx number to increase the amount of memory. The "m" following the number indicates that the memory is measured in megabytes (MB). The correct amount of memory depends on how much the SDS server has and how much it needs for a synchronization. You might need to revise the number several times to set the correct size. For more information on the amount of free RAM required to run SDS, read School Directory Sync requirements.
You might be using a font that's too large for the screen. The dialog box doesn't work with large or extra large fonts. Change your font size or edit your XML file directly.
Troubleshooting tools
Troubleshoot with Configuration ManagerIf you're having trouble getting a synchronization to run properly, check Configuration Manager:
- In Configuration Manager, open the XML file and check the data that you’re using to configure the sync.
- On the Sync page, click Simulate Sync to confirm you completed the required fields.
- On the Notifications page, click Test Notification to confirm you can send a notification.
Quickly identify most issues using the Google Admin Toolbox Log Analyzer.
