Troubleshoot common GCDS issues

Here’s how to troubleshoot problems you might have while configuring Google Cloud Directory Sync (GCDS). You can also check G Suite Known Issues for additional info.

Setup and configuration  |  Errors  |  Users and groups  |  Contacts and calendars  |  Rules

Open all   |   Close all

Setup and configuration

Troubleshoot 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:

  1. In Configuration Manager, open the XML file you're using to configure the synchronization.
  2. On the LDAP Connections page, click Test Connections to confirm you can connect to your LDAP server.
  3. On the Notifications page, click Test Notification to confirm you can send a test notification.
  4. On the Sync page, click Simulate Sync to confirm you have completed all the required fields and to confirm that the synchronization runs.
Troubleshoot a configuration with log files

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.

How does GCDS check certificate revocation lists?

GCDS needs to validate Secure Sockets Layer (SSL) certificates when connecting to Google APIs (over HTTPS) and LDAP over SSL by connecting through HTTP to certificate revocation list (CRL) providers. Sometimes, these validations fail, usually due to a proxy or firewall blocking the HTTP request.

Make sure the GCDS server can access the following URLs over HTTP (port 80):


Additional URLs might be needed if you're using your own certificates for LDAP over SSL.

If you can't enable CRL access, you can disable CRL checks, although this reduces the security of SSL and is not recommended. To do so, edit the sync-cmd.vmoptions and config-manager.vmoptions files in the installation directory of GCDS and add these lines:

Do I need a notification server to run a simulated sync?

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 for your mail server. Otherwise, contact your mail administrator for the correct mail information.

How do I enable full HTTP logging for API requests?

In rare cases, Google Cloud Support may ask you to enable full HTTP logging in addition to enabling 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 enable full HTTP logging:

  1. Make sure GCDS isn't running with either sync-cmd or Configuration Manager.
  2. Navigate to the GCDS installation folder.
  3. Edit the file jre/lib/
  4. 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 = CONFIG = ALL = ALL

  5. Save the file.
  6. 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.

  7. 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.
  • The gcdshttp*.log files generated by the sync.

Using these logs, support can see the information provided by the Directory API to GCDS and how GCDS responds.

Note: If you want to use a debugging proxy, such as Fiddler™, with GCDS, you need to export the Fiddler certificate, add it to GCDS, and disable CRL checks. You can then set Fiddler as the proxy server in GCDS (usually on port 8888) and the connection is logged by Fiddler. For details on how to import the Fiddler root certificate into GCDS's Java truststore, see Certificate-related errors.

How do I open an XML file saved on a different machine or as a different user?

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.

I switched to LDAP+SSL and now my sync is slow

If you have switched to LDAP+SSL and your sync process has slowed: 

  1. Close Configuration Manager.
  2. In the installation directory of GCDS open the sync-cmd.vmoptions and config-manager.vmoptions files using a text editor.

    Note: The installation direction is usually C:\Program Files\Google Cloud Directory Sync (Windows) or ~/GoogleCloudDirSync (Linux).

  3. Edit the files to add the following lines:

    -Dcom.sun.jndi.ldap.connect.pool.protocol=plain ssl
    -Dcom.sun.jndi.ldap.connect.pool.authentication=none simple

  4. Save the files and retry the sync.


Certificate-related errors What if synchronization causes EntityDoesNotExist/EntityExists errors or conflicts?

In your XML configuration file, enable 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.

What if I'm seeing memory-related errors?

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 GCDS. 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 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.

Why does GCDS keep returning an error when the cache is disabled?

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 G Suite 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 -f to 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 G Suite or 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 and groups

Why are some users not synced as groups members?

To synchronize group members separately from the results of any user search rules, GCDS enables the INDEPENDENT_GROUP_SYNC option 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.

If you disable the INDEPENDENT_GROUP_SYNC option, GCDS only uses the results of the user search rules to resolve group members. If some of your users aren't included in your user sync, they won't be synced as group members. This is particularly important if you're syncing shared contacts and you have group members that are contacts—they won't be synchronized as group members.

It's highly recommended to leave INDEPENDENT_GROUP_SYNC enabled. Disabling it is only provided for backwards compatibility and troubleshooting.

Why are some users or groups being recreated with every sync?

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.
  • Enable 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.
Groups with over 1,500 members in Active Directory aren’t syncing correctly

Make sure you have selected MS Active Directory in the server type field of the LDAP Configuration section.

How do I use "Replace domain names in LDAP email addresses"?

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 enable it, 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 disabled, and you're creating an Exact Match exclusion rule, you'd enter as the user's email address to match. If you've enabled Replace domain names in LDAP email addresses, you'd need to use just johndoe. Trying to match won't work, because is stripped prior to the comparison.

Can I nest static and dynamic groups?

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 and calendars

Why 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.

Why don't some users see their main work location in Google Calendar?

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."


Why is a search rule not finding anything?

Check the scope of the rule. You might need to set the scope to SUBTREE.

When creating an exception rule, why can't I see the OK button?

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.
Was this helpful?
How can we improve it?