There are many methods you can use to deploy ArcGIS Enterprise and ArcGIS Server on AWS. This topic describes ways to troubleshoot problems you might encounter with each type of deployment option.
Troubleshoot ArcGIS Enterprise Cloud Builder Command Line Interface for Amazon Web Services
There are two folders under the Logs folder in the location where you extracted the ArcGIS Enterprise Cloud Builder CLI for AWS utility and files.
The Logs folder contains the following two subfolders:
- Log—This folder contains console logs, which are created every time you run the utility. The Log folder also contains CloudFormation event logs for each stack you create as part of deployment every time you run the CREATE command.
- ErrorLog—This folder contains log files to record any errors that occur when you run the ArcGIS Enterprise Cloud Builder CLI for AWS utility. Read these error logs for effective troubleshooting.
Errors encountered when using the ArcGIS Enterprise Cloud Builder CLI for AWS utility
The following are some common messages or problems you may encounter when using the ArcGIS Enterprise Cloud Builder CLI for AWS utility and suggestions on how to correct them.
I receive a permissions error.
The user who runs the ArcGIS Enterprise Cloud Builder CLI for AWS utility must have recursive write access to the Logs and Output folders. Ensure these permissions have been granted.
I receive the message Cannot find file <file_name>.
You must place the JSON configuration files in the Configuration folder or one of its subfolders. If your configuration file was not in this location, move it to the Configuration and run the utility again.
I receive the message Invalid deployment configuration file extension. It must be '.json'.
The configuration file you use must have a .json extension. If it does not, rename it to include this file extension and run the utility again.
I receive the message Invalid JSON format for file <file_name>.
Ensure the configuration file contains valid JSON formatting.
Tip:
You can use a JSON validator such as JSONLint to validate formatting.
I receive the message Failed to access AWS account with provided credentials.
Make sure you provided valid AWS credentials in the JSON configuration file so that the utility can connect to AWS. If credentials are valid, be sure your account is accessible from the machine where you are running the ArcGIS Enterprise Cloud Builder CLI for AWS utility.
I receive an error saying access is denied when I run the ArcGIS Enterprise Cloud Builder CLI for AWS utility with the PREP command.
If you are using an existing S3 bucket for your deployment files, be sure you have appropriate permissions to access and write to the bucket.
When I open the output file after running the ArcGIS Enterprise Cloud Builder CLI for AWS utility with the CREATE command, I do not see all the components I expected.
The output file created when you use the CREATE command contains headings for each component the utility created on AWS. These headings correspond to the nodes you included in your configuration JSON file. The nodes in the configuration file tell the utility which components to create. If you leave out a node from the configuration file, the utility will not create that component.
Each node you include in your configuration file must contain at least one parameter. Even if you set all the parameters under the "Default" node, you must include a node for every part of the deployment you want created and that node must contain at least one parameter and value. If a node is present in the configuration file but does not include a parameter, the utility skips that node. For example, you cannot set parameters for an ArcGIS GIS Server site in the "Default" and place an empty "Server" node in the configuration file. If you do that, the utility will not create the ArcGIS GIS Server site.
Check the configuration file to ensure you have added all required nodes and at least one parameter for each component of the deployment. See ArcGIS Enterprise Cloud Builder CLI for AWS parameters for a list of required parameters for each node in the configuration file.
When I run the ArcGIS Enterprise Cloud Builder CLI for AWS utility, the command prompt appears to stop running.
If you find the ArcGIS Enterprise Cloud Builder CLI for AWS utility or any utility you run in a Microsoft Windows command window stops running, disable QuickEdit Mode for the command window.
Troubleshoot AWS CloudFormation stack creation
Use the AWS CloudFormation console to monitor the status of your AWS CloudFormation stack and detect if stack creation fails. Log in to the AWS CloudFormation console (which is part of the AWS Management Console) and open the Events tab to find information on stack creation, updates, and deletions. If the stack fails to create, information on the Events tab usually gives you a general idea what has gone wrong.
The Esri CloudFormation templates also create log files on the virtual machines to help you troubleshoot issues. To be sure the files are preserved even when deployment launch fails, sign into the AWS CloudFormation Console and disable Rollback on failure.
If your deployment fails when launching from an Esri template, make a remote desktop connection or SSH to the EC2 instance to view the logs. Log types and locations are listed in the following table:
| EC2 instance type | Log file and location on EC2 instance | Log file description |
|---|---|---|
Ubuntu | /var/log/cfn-init.log | Log file for the CloudFormation helper script used to retrieve and interpret the resource metadata, install packages, create files, and start services |
/var/log/chef-run.log | Chef configuration management tool log file | |
/var/lib/tomcat7/logs/catalina.out | Apache Tomcat application server log file | |
Windows | C:\cfn\log\cfn-init.log | Log file for the CloudFormation helper script used to retrieve and interpret the resource metadata, install packages, create files, and start services |
C:\chef\chef-run.log | Chef configuration management tool log file |
Note:
If CloudFormation stack creation succeeds, the stack output parameters provide a link to the log group in the AWS Management Console. If stack creation fails, go to the CloudFormation Resources list in the AWS Management Console to find the log group. Note that if stack creation fails before any instances are launched, a log group might not be created.
Errors encountered when launching an AWS CloudFormation stack
The following are some common messages or problems you may encounter when you deploy using an AWS CloudFormation template and suggestions on how to correct them.
Why do I see an error about insufficient capacity when I click Launch to launch an instance?
This is an error from Amazon EC2 meaning that it does not have the available capacity to meet your request for a new instance. If your deployment architecture permits, you may be able to work around this error by requesting an instance in a different availability zone or letting EC2 choose the availability zone for you. Other options are to try launching a different size of instance or launching the instance later.
What does the message Error encountered during build of config: Failed to retrieve https:// .s3.amazonaws.com/ in cfn-init.log mean?
If you see this message in the cfn-init.log file, ensure the deployment S3 bucket name is correct and that the S3 object key name of authorization files and SSL certificates are correct.
What does the message Unable to connect to WebAdaptor URL : https://agsportalssl.esri.com/server/webadaptor in the catalina.out log file
If you see this message in the catalina.out log file on an Ubuntu instance, ensure the SSL certificate in the deployment S3 bucket is valid and in PKCS 12 format. Also be sure the provided SSL certificate password is correct.
What does the message OpenSSL::PKCS12::PKCS12Error: PKCS12_parse: mac verify failure in the chef-run.log file mean?
If you see this message in the chef-run.log file on a Windows instance, ensure the SSL certificate in the deployment S3 bucket is valid and in PKCS 12 format. Also be sure the provided SSL certificate password is correct.
Troubleshoot AWS Management Console
You might encounter one of the following error messages when you use the AWS Management Console and Esri Amazon Machine Images to manually create your site:
Why do I receive the message No password was found. when I try to retrieve the administrator password for my EC2 instance on Windows?
This message can appear if you try to use Get Windows Password after you have stopped and started an EC2 instance. To avoid this error, the first time you log in, change the Administrator password to a value you can more easily remember.
I got a message in the AWS Management Console that my instance is scheduled for retirement. What does this mean?
You may see this message if your instance happens to be running on degraded hardware that Amazon needs to replace. If you see this message, you should stop your site and start it again.
Note that if you used ArcGIS Server Cloud Builder on Amazon Web Services to create your site, use Cloud Builder to stop and start the site.
After you restart the site, the message should go away.
Troubleshoot ArcGIS Server Cloud Builder on Amazon Web Services
If you encounter issues when using ArcGIS Server Cloud Builder on Amazon Web Services, you can create a text file that captures error logs and other information to help you troubleshoot the problem.
Follow these steps to enable debug-level logging for ArcGIS Server Cloud Builder on Amazon Web Services:
- If ArcGIS Server Cloud Builder on Amazon Web Services is running, close it.
- Create a plain text file named loglevel in the %USERPROFILE%\documents\ArcGISCloudBuilder folder on the machine where ArcGIS Server Cloud Builder on Amazon Web Services is installed.
Do not include any extension on the file name; for example, the file must be named loglevel, not loglevel.txt.
- Open the file in a text editor and type DEBUG on the first line.
- Save and close the file.
- Restart ArcGIS Server Cloud Builder on Amazon Web Services and repeat the steps that led to the problem you are trying to troubleshoot.
Debug-level logs will now be written to a log file. When ArcGIS Server Cloud Builder on Amazon Web Services writes to the log file, the file name will have the date appended to the end of it in the format YYYY-MM-DD.
A new log file is created each day ArcGIS Server Cloud Builder on Amazon Web Services is used. Be sure to delete old log files.
Errors encountered when using ArcGIS Server Cloud Builder on Amazon Web Services
The following are some common messages or problems you may encounter when you create an ArcGIS Server site using ArcGIS Server Cloud Builder on Amazon Web Services and suggestions on how to correct them.
Why can't I make a remote desktop connection to my newly created ArcGIS Server site on Windows?
First, allow some time for the site to launch. If you used ArcGIS Server Cloud Builder on Amazon Web Services to create the site, wait until all the site information appears in the My Sites window and you see such buttons as those used for stopping, updating, and deleting a site.
If you launched the site using the AWS Management Console or a CloudFormation template, right-click the instance in the AWS Management Console and click Get System Log. Once you see a message that Windows is ready to use, wait about 5 additional minutes before you attempt to log in.
Second, make sure you've added a rule to your site's security group allowing remote desktop connections through port 3389. This is described in Open an Amazon EC2 security group for ArcGIS.
ArcGIS Server Cloud Builder on Amazon Web Services displays the following message after I log in: Failed to get a list of custom configuration templates. Forbidden. What does this mean?
Although this message might have multiple causes, it can appear when your system time is out of sync with the actual current time. For example, if you live in a region where the time moves forward an hour during the summer months, and your computer's clock is not synchronized with this change, ArcGIS Server Cloud Builder on Amazon Web Services cannot perform certain actions with Amazon EC2.