Troubleshooting the Amazon Toolkit for Visual Studio - Amazon Toolkit with Amazon Q
Troubleshooting best practicesViewing and filtering Amazon Q security scansThe Amazon Toolkit isn't properly installedFirewall and proxy settings
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Troubleshooting the Amazon Toolkit for Visual Studio

The following sections contain general troubleshooting information about the Amazon Toolkit for Visual Studio and working with Amazon services from the toolkit.

Note

Installation and set-up-specific troubleshooting information is available in the Troubleshooting installation issues topic, located in this User Guide.

Troubleshooting best practices

The following are recommended best practices when troubleshooting Amazon Toolkit for Visual Studio issues.

  • Repair Visual Studio and restart your system

  • Attempt to recreate your issue or error prior to sending a report.

  • Take detailed notes of each step, setting, and error message during the recreation process.

  • Collect Amazon Toolkit Logs. For a detailed description of how to locate your Amazon Toolkit logs, see the How to locate your Amazon logs procedure, located in this guide topic.

  • Check for open requests, known solutions, or report your unresolved issue in the Amazon Toolkit for Visual Studio Issues section of the Amazon Toolkit for Visual Studio GitHub repository.

Repair Visual Studio and Restart your system

  1. Close all running instances of Visual Studio.

  2. From the Windows start menu, Launch Visual Studio Installer.

  3. Run Repair on the affected installation(s) of Visual Studio. This allows Visual Studio to rebuild its index of installed extensions.

  4. Restart Windows prior to re-launching Visual Studio.

How to locate your Amazon Toolkit logs

  1. From the Visual Studio main menu, expand Extensions.

  2. Choose the Amazon Toolkit to expand the Amazon Toolkit menu, then choose View Toolkit Logs.

  3. When the Amazon Toolkit logs folder opens in your Operating System, sort the files by date and locate any log file that contains information relevant to your current issue.

Viewing and filtering Amazon Q security scans

To view your Amazon Q security scans in Visual Studio, open the Visual Studio Error List by expanding the View heading in the Visual Studio main menu and choosing Error List.

By default, the Visual Studio Error List displays all of the warnings and errors for your code base. To filter your Amazon Q security scan findings from the Visual Studio Error List, create a filter by completing the following procedure.

Note

Amazon Q security scan findings are only visible after security scan has run and detected issues.

Amazon Q security scan findings appear as warnings in Visual Studio. In order to view Amazon Q security scan findings from your Error List, the Warnings option in the Error List heading must be selected.

  1. From the Visual Studio main menu, expand the View heading and choose Error List to open the Error List pane.

  2. From the Error List pane, right-click the header row to open the context menu.

  3. From the context menu, expand Show Columns, then select Tool in the expanded menu.

  4. The Tool column is added to your Error List.

  5. From the Tool column header, select the Filter icon and choose Amazon Q to filter for Amazon Q security scan findings.

The Amazon Toolkit isn't properly installed

Issue:

Within one minute after starting Visual Studio, the Amazon Toolkit for Visual Studio the following messages appear in the output pane and info bar, respectively:

Some Toolkit components could not be initialized. Some functionality may not work during this IDE session.

The Amazon Toolkit is not properly installed.

Solution:

It's possible that updating or installing an extension caused some of Visual Studio's internal cache files to go out-of-sync. The following procedure describes how to have these files rebuilt the next time that you launch Visual Studio.

Note

It's possible that this solution may impact your Visual Studio customizations. After completing this procedure, the Amazon Toolkit extension should be listed as installed and no longer report an error message. If you continue to experience this issue after completing the following steps, please see Issue #452 in the Amazon Toolkit for Visual Studio GitHub repository for additional information.

  1. Install the latest version of Visual Studio 2022.

    Note

    The minimum required version is 17.11.5.

  2. Close all running instances of Visual Studio.

  3. From Windows, open the Developer Command Prompt as an Administrator.

  4. From the Developer Command Prompt, run the following command: devenv /updateconfiguration /resetExtensions, then wait for the command to finish.

  5. After the command has finished, restart Visual Studio.

  6. In Visual Studio the Amazon extension is now listed as installed and no longer reports the error messages listed at the top of this issue.

Firewall and proxy settings

Troubleshooting firewall and proxy settings

Security-scanning software can interfere with your ability to download files from Amazon Toolkit language servers by removing files from downloads or preventing downloads altogether.

To check your firewall and proxy settings, navigate to https://aws-toolkit-language-servers.amazonaws.com/codewhisperer/0/manifest.json from an internet browser installed on the same system as your instance of Visual Studio. If you encounter an error or the page is unable to load, then there may be a firewall or proxy filter preventing you from reaching aws-toolkit-language-servers.amazonaws.com.

Custom certificates

The Amazon Toolkit for Visual Studio utilizes a language server that runs on the Node.js runtime. For detailed information about how to check if your network uses a custom certificate, see the Configuration and credential file setting in the Amazon CLI topic in the Amazon Command Line Interface User Guide for Version 1.

To configure your proxy settings and define a certificate, you must configure your HTTPS_PROXY env variable and create Windows Environment Variables for the NODE_OPTIONS and NODE_EXTRA_CA_CERTS keys.

To configure your HTTPS_PROXY env variable, complete the following steps.

  1. From the Visual Studio main menu, choose Tools, then choose Options.

  2. From the Options menu, expand Amazon Toolkit, then choose Proxy.

  3. From the Proxy menu, define your Host and Port.

Note

For information about configuring the HTTPS_PROXY from the Amazon CLI, see the Using an HTTP proxy for the Amazon CLI topic in the Amazon Command Line Interface User Guide.

Create Windows Environment Variables for the following keys.

  • NODE_OPTIONS = --use-openssl-ca

  • NODE_EXTRA_CA_CERTS = Path/To/Corporate/Certs

Note

For more information about extracting corporate root certificates, see the Export a certificate with its private key article at learn.microsoft.com. For detailed information about the Windows Environment Variable keys, see the Node.js v23.3.0 documentation at nodejs.org.

Allow listing and additional steps

In addition to interfering with Amazon Toolkit language servers, firewall settings can prevent Amazon Q from uploading to Amazon S3 and calling the service API. To minimize the potential of these errors, we recommend allowing outbound internet access on port 443 (HTTPS) for the following endpoints:

  • https://codewhisperer.us-east-1.amazonaws.com/

  • https://amazonq-code-transformation-us-east-1-c6160f047e0.s3.amazonaws.com/

  • https://aws-toolkit-language-servers.amazonaws.com/

  • https://q.us-east-1.amazonaws.com

  • https://client-telemetry.us-east-1.amazonaws.com

  • https://cognito-identity.us-east-1.amazonaws.com

  • https://oidc.us-east-1.amazonaws.com

If you continue to encounter firewall and proxy issues, then collect your Amazon Toolkit Logs and reach out to the Amazon Toolkit for Visual Studio team through the Amazon Toolkit for Visual Studio issues section of the Amazon Toolkit for Visual Studio GitHub repository. For details on collecting your Amazon Toolkit Logs, review the information in the Troubleshooting best practices section of this User Guide topic.