Troubleshoot ImportUsers tool errors
The tool provides the following types of detailed error information to help you troubleshoot issues:
-
Console (or specified file). Provides information about system errors.
-
Audit trail. Contains information about actions the tool performs on user and the resulting status or error.
-
Diagnostic information (ImportUsers tool 4.6.2 or later). Provides information for monitoring the tool's progress and activity.
For more details about the content and location of these items, see Status and error information.
To troubleshoot ImportUsers tool errors
There are three main types of errors you might encounter while running the ImportUsers tool:
-
Confirmation prompt indicates the wrong customer
If your environment supports multiple customers and the tool's confirmation prompt indicates a customer other than expected, there are a few steps you need to take to correct it. (See more)If the confirmation prompt displays the wrong customer:
-
Type
N
to exit the tool. -
Close any browsers that have the CMX web application open.
-
Run the tool again and, if prompted for credentials (when not using the
-preservelogin
option), ensure you enter ones for a Bulk Importer in the customer you want to manage. -
If the problem persists, contact Support.
-
-
System errors
System errors typically occur when there are errors in the command-line syntax or CSV file format. (See more)If you encounter a system error while running the tool:
-
Correct any errors in the following, and then run the tool again:
-
Command-line options
Ensure you have specified all command-line options correctly and have provided the appropriate value for each one. To review the set of command-line options, see ImportUsers tool syntax.
-
CSV file contents
Ensure that each row contains all required columns and the number of headers matches the number of data columns. To learn which columns the CSV requires, see ImportUsers CSV file reference. Place corrections to failed rows in a new CSV file, and then run the tool again.
-
-
If either no corrections are required or the error still occurs after making corrections, perform the following steps:
-
Delete
cmxEmailUserName.properties
(ortool.properties
for pre-4.6.2 tool versions) from the home directory of the user account that ran the tool. -
Clear the cache and cookies of your default web browser.
-
Run the tool again.
-
- If the problem persists, contact Support.
-
-
Timeouts or Server errors having an HTTP 5XX status code (ImportUsers tool 4.6.2 or later)
Timeouts and server errors can result from temporary network issues or a heavy system load. If the diagnostic information incmx-import-users-tool.log
indicates a server error having an HTTP 5XX status code, such as a Gateway timeout (HTTPStatus=504
), there are two command-line options that can help. (See more)TIP: When rerunning the ImportUsers tool 4.7.0 or later, do not change the CSV file (so it has the same MD5 checksum) and specify the same output location (
-outputDir
option) for its audit file. This quickens the retry process by ensuring the tool retries only rows that failed or were not processed due to timeout or server error.If the tool encounters a timeout or server error:
-
For a timeout error, use the
-batchsize
option to reduce the number of users in each batch.By default, the tool sends groups of 25 users (100 in version 4.6.2) to the CMX server for processing. However, network connectivity or load issues might prevent the tool from receiving the results for batches this size before its connection to the server expires.
To work around this issue, rerun the tool several times, decreasing the batch size each time, to a minimum size of 5, until the tool does not encounter an error. If a timeout still occurs when using a batch size of 5, continue with the next step.
-
(ImportUsers tool 4.7.0 or later) Use the
-retrycount
option to increase the number of times the tool resends a request to the CMX server.Rerun the tool several times, increasing the retry count by one, to a maximum of 10, until the tool does not encounter an error. If a server error still occurs when using the maximum retry count, continue with the next step.
-
If the problem persists, contact Support.
-
If you encounter a different type of error that you are not able to resolve, contact Support for help.