Here’s how to troubleshoot problems you might have while configuring Google Cloud Directory Sync (GCDS). You can also check Google Workspace Known Issues for additional info.
Try the Log Analyzer
This tool can identify most issues within a few moments of submission.
Get details on how to enable trace-level logging.
Setup & configurationTroubleshoot a configuration using Configuration Manager
If you're having trouble getting a synchronization to run properly, confirm that the configuration information is correct in Configuration Manager and note which tests fail:
- In Configuration Manager, open the XML file you're using to configure the synchronization.
- On the LDAP Connections page, click Test Connections to confirm you can connect to your LDAP server.
- On the Notifications page, click Test Notification to confirm you can send a test notification.
- On the Sync page, click Simulate Sync to confirm you have completed all the required fields and to confirm that the synchronization runs.
To troubleshoot a configuration using log files, submit generated logs to the Log Analyzer.
Most issues can be identified within a few moments of submission.
To run a simulated synchronization, you need a server capable of sending mail. If you're running GCDS on a mail server machine, you can use the IP address 127.0.0.1 for your mail server. Otherwise, contact your mail administrator for the correct mail information.
In rare cases, Google Cloud Support may ask you to turn on full HTTP logging in addition to turning on trace-level logging in GCDS. Full HTTP logging is used to see the exact API request made by GCDS and the response provided by the Google APIs.
Important: Full HTTP logs can contain highly sensitive information. Remove any sensitive information (such as current refresh_token or access_token fields) before sending the logs to support.
To turn on full HTTP logging:
- Make sure GCDS isn't running with either sync-cmd or Configuration Manager.
- Navigate to the GCDS installation folder.
- Edit the file
- Add the following lines to the end of the file:
java.util.logging.FileHandler.pattern = %h/gcdshttp%u.%g.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 100
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
handlers = java.util.logging.FileHandler
com.google.api.client.http.level = CONFIG
com.google.gdata.client.http.HttpGDataRequest.level = ALL
sun.net.www.protocol.http.HttpURLConnection.level = ALL
- Save the file.
- Run another GCDS sync (with logging set to Trace).
Log files named gcdshttp*.log are created in homedir (Linux) or profile folder (Microsoft Windows). Archive these files together, because they can be quite big.
- Delete the lines added in step 4 to prevent large log files being created in the future.
Then, provide the following files to support:
- The XML file used.
- The trace-level logs from the latest sync.
gcdshttp*.logfiles generated by the sync.
Using these logs, support can see the information provided by the Directory API to GCDS and how GCDS responds.
Logged request and response bodies are each limited to a size of 16 KB. If you see a log entry that's truncated because it’s exceeding that limit, use Fiddler as suggested below.
Note: If you want to use a debugging proxy, such as Fiddler, with GCDS, you need to update the .vmoptions files to set GCDS to use the Windows trusted certificate store, and turn off CRL checks. You can then set Fiddler as the proxy server in GCDS (usually 127.0.0.1 on port 8888) and the connection is logged by Fiddler. If you're using GCDS on Linux, you can't use the Windows trusted certificate store, so you need to import the Fiddler root certificate into GCDS's Java trust store. For more information, see, go to Import the server certificate.
See Work with configuration files for instructions on how to open an XML file that was saved on a different machine, or as a different user on the same machine.
ErrorsWhat if synchronization causes EntityDoesNotExist/EntityExists errors or conflicts?
In your XML configuration file, set the useDynamicMaxCacheLifetime option. This option configures GCDS to cache data for a maximum of 8 days, and clear the cache more frequently in small-to-medium data sets to reduce the chance of cached data growing stale or conflicting with new data. The useDynamicMaxCacheLifetime option is automatic in configurations created with GCDS 3.2.1 and above.
Note: These errors usually occur when modifications are done directly in your Google domain. When using GCDS to sync, you should avoid making changes to your Google domain directly. Instead, make changes to users, groups, and other entities in your LDAP directory. Then, use GCDS to sync these changes to your Google domain.
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
config-manager.vmoptions files in the installation directory of GCDS. The relevant entries look like this:
-Xmx1000m(the maximum amount of memory allocated for the heap size)
-Xms64m(the minimum amount of memory allocated for the heap size)
Edit both the
config-manager.vmoptions files so that the change applies to both sync-cmd and Configuration Manager versions.
-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 GCDS 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 GCDS, read System requirements for GCDS.
This might be a configuration issue, such as an exclusion rule misconfiguration. This kind of misconfiguration can be hidden by GCDS caching.
GCDS keeps a cache of data for your Google service (such as Google Workspace or Cloud Identity) for a maximum of 8 days. GCDS might clear the cache more frequently, depending on the cached data size. However, if the cache isn't cleared, you might not see your updates for up to 8 days.
You can manually clear the cache:
- Run a sync from Configuration Manger and select to clear the cache when performing a sync.
- Use the command line
flag -fto force a flush of the cache.
- Modify the XML config file to set the maxCacheLifetime value to 0.
Important: Forcing a flush of cache can dramatically increase synchronization time.
For example, you sync your LDAP data and create a new group for your Google service (such as Google Workspaceor Cloud Identity). You then create an exclusion rule to exclude that group from subsequent syncs. That exclusion rule is misconfigured and will fail. However, the subsequent sync calls on cached data and the group remains in your Google service. When you sync again with clear cache, the misconfiguration causes the group to be removed from your Google service.
Users & groupsWhy are some users not synced as group members?
To synchronize group members separately from the results of any user search rules, GCDS turns on INDEPENDENT_GROUP_SYNC by default. If you're using member-reference attributes for group synchronizations, GCDS tries to resolve the email address of every user in the LDAP directory, regardless of any user search rules.
To synchronize group members based on only the results of user search rules, remove INDEPENDENT_GROUP_SYNC from your configuration XML file. GCDS:
- Uses the results of the user search rules to resolve group membership
- Only syncs as group members those users included in your user sync
- Executes user search rules, even if you turn off user account sync in General Settings
(However, the results don’t sync to Google as users but as group members, if the eligible users also qualify as group members.)
Typically, this isn’t how you want your sync to run, particularly if you're syncing shared contacts and have group members that are contacts. In this case, the contacts won't synchronize as group members.
This happens when the LDAP attribute configured as the Group Name Attribute doesn't contain a full email address. To resolve this issue, check your Group Search rules and make sure that GCDS uses a full email address for the group names. Use one of the following methods:
- Set the Group Name Attribute to a different LDAP attribute that specifies a full email address for each group, such as mail.
- Turn on Replace domain names in LDAP email addresses in the Google Domain Settings, so that your Group Name Attribute matches the Google-side group names.
- Add the domain name to the group name by specifying a Group Name Suffix in your Group Search Rule.
Make sure you have selected MS Active Directory in the server type field of the LDAP Configuration section.
This option (shown as
SUPPRESS_DOMAIN in the XML file) is used if the email addresses in the LDAP directory are in a different domain than your Google domain. When you turn it on, GCDS strips the domain part off all of the email addresses it reads.
Any processing is done without the domain name. If you use exclusion rules based on email addresses, you need to consider only the local part of the email address for the exclusion rule.
For example, if you have Replace domain names in LDAP email addresses turned off, and you're creating an Exact Match exclusion rule, you'd enter email@example.com as the user's email address to match. If you've turned on Replace domain names in LDAP email addresses, you'd need to use just johndoe. Trying to match firstname.lastname@example.org won't work, because @example.com is stripped prior to the comparison.
When provisioning groups using GCDS, you can't nest dynamic groups underneath static groups (or static groups underneath dynamic groups). GCDS requires static groups to be queried separately from dynamic groups, however all nested groups have to be a part of the same query.
Find a way to implement dynamic groups as static groups, possibly by automating a task that periodically queries every dynamic group to populate static groups in the directory. GCDS can then use the static groups (as created from the dynamic groups) for provisioning and not provision the dynamic group.
Contacts & calendarsWhy do I see duplicate contacts in my domain directory after syncing with GCDS?
This usually happens if you're syncing shared contacts and the search rules are built incorrectly.
There are 2 types of relevant objects that you can sync with GCDS:
- User profiles—Users in your Google domain with additional data such as a phone number or address. You can only sync a profile for a user that exists in your domain.
- Shared contacts—Contacts of external parties that users in your domain need to contact.
To resolve this issue, correct your shared contact search rules to exclude users in your own domain. On the next sync, GCDS attempts to delete the redundant contacts. You might need to adjust the shared contact deletion limit for that first sync.
In some circumstances, users don't see their main work location in Google Calendar when scheduling or arranging meetings.
If you see this issue, make sure that the location type and area attributes are set to "desk."
RulesWhy is a search rule not finding anything?
If you're having problems with search results, check:
- The scope of the rule. You might need to set the scope to Sub-tree.
- The search rule that you're using is correct.
- The attributes that are used exist and are visible.
- Your LDAP query. Verify the query on your LDAP server using the same admin username that's configured in GCDS.
For more details, go to Use LDAP search rules to synchronize data.
You might be using a font that is too large for the screen. The dialog box does not work with large or extra large fonts. Change your font size or edit your XML file directly.
Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.