Find common User Sync Tool errors and how to resolve them.
This page lists common errors you may encounter when running the User Sync Tool, along with steps to resolve each. For an overview of the tool and where to find the setup, configuration, and command reference, see Set up the User Sync Tool.
Installation and environment
This can appear on Windows when paths exceed 256 characters. Create an environment variable named PEX_ROOT with the value C:\pex. If you run the script from a drive other than C:, change the drive letter to match. A system restart is sometimes required for the change to take effect.
Run the python command line from inside the folder where user-sync.pex is located.
- Check whether the Python version installed on your system is 32-bit. Uninstall the 32-bit version and install the 64-bit version.
- Check whether the user-sync.pex version you downloaded from GitHub matches your Python version and operating system. For example, download user-sync-v2.3-win64-py365.zip for Windows 64-bit and Python 3. Match the Python version the .pex was built with rather than using the latest Python. The suffix of the .zip identifies the version: for user-sync-v2.3-win64-py365.zip, that is Python 3.6.5.
This error was recorded on macOS High Sierra using User Sync Tool v2.3 and Python 3.7.0. Running brew install openssl in the Terminal resolved it for that scenario.
Connection, timeouts, and throttling
If the timeout is less than 30 minutes, these warnings appear when the quota of API calls allowed within one minute is reached. The tool uses an exponential back-off mechanism to retry, increasing the time between retries, and stops after three failed attempts. Let the script run to the end.
If the timeout is higher than 1000 seconds, throttling is related to how often each User Sync Tool instance runs. An instance that runs too frequently is throttled for 30 to 75 minutes. The timeout only pauses the tool for a period; the tool recovers and continues the sync afterward.
Because the tool detects when two instances start at the same time, no new instance runs until the first finishes. In this case, the log may show a message that a process is already in progress.
For best performance, follow these run-frequency recommendations:
- Set the scheduled task to repeat at least 2 hours apart.
- Set the scheduled task trigger so it does not start on the :00 or :30 minute mark, to avoid peak traffic.
- If you must run the tool more often, consider using the push strategy (delta of changes) instead of a full sync.
- Match the tool's run schedule to your organization's workday. For example, do not run sync jobs at night if your organization does not need to modify provisioning then.
The tool cannot connect to the public API endpoints. Local settings such as firewall rules, a proxy blocking traffic, or account internet-access settings can prevent access. Adding the https_proxy environment variable with a value such as http://<proxyAddress>:<port> or https://<proxyAddress>:<port> can help. In other cases, allow access to these endpoints: ims-na1.adobelogin.com:443 and usermanagement.adobe.io:443. This can only be resolved locally by clearing access to these endpoints for the running account.
SSL inspection on the local proxy server causes this.
Solution 1: Obtain the proxy's root CA certificate in PEM format (for example, thecert.crt). If it is in DER format, convert it to PEM with this openssl command: openssl x509 -inform DER -in thecert.crt -out thecert.pem -outform PEM. A PEM file shows a base64-encoded string between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Create an environment variable named REQUESTS_CA_BUNDLE and set its value to the path of thecert.pem.
Solution 2: On Windows, this error can occur if the tool runs from a different drive than the one where the operating system and Python are installed. Move the entire script to the drive where the operating system is. If that is not an option, copy the cacert.pem file that contains the trusted root CAs to the other drive and set its path as REQUESTS_CA_BUNDLE. If a proxy also inspects SSL traffic, copy the proxy root CA certificate content into cacert.pem so the proxy certificate is trusted. A default Python install keeps the certificate bundle at C:\Python36\Lib\site-packages\certifi\cacert.pem.
Solution 3: Disable SSL inspection on the proxy for the API endpoints ims-na1.adobelogin.com and usermanagement.adobe.io.
Authentication and credentials
The Credentials Store entry for umapi_api_key may be missing. Create the entry in the Credentials Store. See the User Sync Tool documentation on storing credentials in OS-level storage.
The value may also have been added to the Credentials Store under a different user account while the entry is missing for the currently connected user. Add it, or switch user accounts.
- If you cannot quickly identify the problem, reissue the key pair.
- Do not use the umapi_private_key_data attribute when you run the script on Windows. Instead, encrypt the key and store the password in the Credential Manager.
- If you used a different format to issue the key pair, try an RSA 256, 2048-bit private key.
- You may have set secure_priv_key_pass_key: umapi_private_key_passphrase in the connector-umapi.yml file. Make sure the matching entry in the Credential Store and its associated values match.
In the Adobe Admin Console, go to Settings, then Authentication Settings. An option other than Easiest for Users (password never expires) may be selected. The More Secure or Most Secure option can expire the password of the technical account linked to the integration. To fix this, create a new integration and renew the metadata in the connector-umapi.yml file. A fix was deployed for this, but it can affect integrations created before October 2018.
- The tech_acct value in the connector-umapi.yml file may differ from the technical account ID in the integration in the Adobe Developer Console. Verify the technical account ID in the current integration and copy it to the file.
- The public certificate from the integration may be expired. Renew the private and public key, upload the public key, and replace the old private key with the new one. Verify the path in the connector-umapi.yml file points to the correct file.
- Confirm the integration is for the correct organization. Select the organization from the dropdown in the upper-left corner of the Adobe Developer Console, then verify the technical account ID for the active integration along with the other metadata (organization ID, secret, and client ID).
This error appears on older integrations. Create a new integration (or project) in the Adobe Developer Console alongside the existing one used for the same purpose. The new integration provides new credentials, so update them in the connector-umapi.yml file. The key pair (private and public key) is likely reissued, so the new private key must replace the existing one.
LDAP and groups
- The group does not exist in LDAP with that exact name. Add the correct LDAP name of the group.
- The group is not discoverable under the declared base_dn (see the connector-ldap.yml file). Change the base_dn value to include the group. This mainly occurs when base_dn points to a specific OU instead of being as broad as possible.
The user group group_name in the output does not exist on the Adobe side. Create it. If you intended to set the name of a product license configuration (PLC) rather than a user group, see the User Sync Tool documentation on creating corresponding groups in your enterprise directory.
The groups of interest may be in a subdomain while the host value is one of the root domains. Change the host value to a subdomain where the user groups are found. If users or groups are in both the root domain and its subdomains, use the global catalog port on the root domain and change the subdomain groups to Universal instead of Global. Example host value using the global catalog: ldap://domain.local:3268 or ldaps://domain.local:3269. When you use the global catalog port, set base_dn to an empty value: base_dn: "".
Users and account creation
The domain used to create the account may not be claimed or trusted in your organization. A green flag or dot appears for active domains in the Adobe Admin Console under Settings. If it does not, completing the domain claim process can resolve this.
An attempt was made to create a Federated ID account, but the directory is created for Enterprise ID, or the reverse. Find the user_identity_type attribute in the user-sync-config.yml file. Set the value to match the directory type shown in the Adobe Admin Console (Settings, then Identity, then Domains, then the Directory type value for the domain).
Sometimes the @claimed-domain.com domain is owned by a different organization that set up an Azure or Google connector to sync accounts to the Admin Console, and the domain is then trusted to a different organization that uses the User Sync Tool to sync accounts of the format @claimed-domain.com. The message appears when the tool extracts the user@claimed-domain.com account from an LDAP server to create it in the secondary organization, but the account is not yet created or synced in the main organization through the Azure or Google connector. Create or sync the user@claimed-domain.com account in the organization that uses the Azure or Google connector, then retry the sync with the User Sync Tool in the trustee organization.
This generic error has multiple causes, but the usual problem is that the domain used in the create action is under an Azure or Google sync setup. To check, sign in to the Adobe Admin Console with the System Administrator account, go to Settings, select the directory that holds the domain, and select the Sync tab. If a Sync Source card is present, the fix depends on how synchronization should continue:
- If the Azure or Google connector should do the sync, continue with the Sync Source setup and remove the User Sync Tool completely.
- If the User Sync Tool should do the sync, select Go to Settings, then Remove Sync at the bottom of the page. The tool then runs as usual.
If no Sync Source card is present, the current tool may run against a Console where the domain is entrusted from a different Console (the owning organization). That organization may have Azure or Google sync turned on, which causes this error. Sync the account in the owning Console first, then use the tool to create the account in the current Console.
If none of these fit, contact Enterprise Support.
