故障排查

常见登录问题 #

We couldn’t load your Q Developer profiles #

请首先确认登录时 StartURL 和 Region 是否选择正确。如有需要，请联系您的管理员获取正确的 StartURL 和 Region。

如果确认 StartURL 和 Region 无误，可以参考下文，查看 Q 的日志来排查问题。

以下是日志中的报错示例

WARN - software.aws.toolkits.jetbrains.services.amazonq.profile.QProfileResources - Failed to list Q profiles for region us-east-1
software.amazon.awssdk.services.codewhispererruntime.model.AccessDeniedException: The bearer token included in the request is invalid. (Service: CodeWhispererRuntime, Status Code: 403, Request ID: xxx)

如果报错中的 region 和您填写的 region 不同，您可以尝试清除用户目录下的 .aws 文件夹的全部文件后，重新登录。

除此之外，在 JetBrains IDE 中，您可以使用 JetBrains IDE 的 Invalidate Caches 清除一下缓存再重试。参考 JetBrains 官方文档。

登录报错：您没有问题，而是我们遇到了问题 #

请先检查您是否在登陆界面选择了企业版（Pro tier），并且提供了正确的 StartURL 和 Region（区域选择与 AWS Identity Center 所在的区域保持一致）。请注意区分登陆界面的企业版和个人版（AWS Builder ID）。

如果上述信息无误，请检查您的系统时间是否正确。

登录报错：Invalid Callback URL #

请首先确认登录时 StartURL 和 Region 是否选择正确。如有需要，请联系您的管理员获取正确的 StartURL 和 Region。

登录报错：有些内容无法计算 #

请首先确认登录时 StartURL 和 Region 是否选择正确。如有需要，请联系您的管理员获取正确的 StartURL 和 Region。

如果报错信息是：“有些内容无法计算：我们无法验证您的登录凭证，请重试”，说明您的用户名或密码填写有误。

错误：not authorized to make this call #

登录成功后在 IDE 聊天面板中报错没有权限。

通常是由于用户是通过 AWS Identity Center Group 的方式添加的，这种情况下需要等待一段时间用户才能生效，不超过 24 小时。详情请查看文档。

如果您着急使用，请通过 User 的方式添加用户！

IDE 常见错误 #

Android Studio 无法展开聊天面板 #

参考 安装与登录 中的 Android Studio 章节，安装带有 JCEF 的 boot runtime

JetBrains IDE 安装报错 Requires plugin ‘aws.toolkit.core’ to be installed #

参考 安装与登录 中的 JetBrains IDE 章节，先安装 AWS Core 插件

Too much context loaded #

说明上下文内容太多，可以尝试使用 /compact 指令压缩当前会话的上下文，或新开一个会话。

如果新开会话，立刻出现此报错，通常原因为：1）README 文件以及 .amazonq/rules/ 文件夹内的内容太多。Amazon Q 会自动加载这些文件到上下文，如果内容太多，会把上下文撑满。2）MCP 配置过多，导致 MCP 工具描述占满上下文，请尝试禁用一些 MCP 服务器。

错误：unable to get local issuer certificate #

通常是系统证书存在问题。您可以尝试在系统 shell 中（比如 Windows 的 cmd）执行 curl https://baidu.com 看看会不会有类似的证书问题。您需要联系您企业的 IT 服务来修复您本机的证书问题。

错误：编辑文件失败 #

在 Agentic Coding 模式下自动编辑文件可能会失败，您可以将鼠标悬浮在红色错误图标上查看具体的错误信息。

原理: Agent 在编辑文件时会先搜索一个 pattern，然后替换它为新的代码块。如果这个 pattern 在文件中有多个匹配或者没有匹配，agent 就会无法替换代码块从而报错。

通常导致这些问题的原因包括：

  1. 文件被人类或其他工具修改后没有被 AI 重新读取
  2. 文件太长，导致简单的 pattern 在同一个文件中出现多次
  3. 需要搜索的 pattern 过于复杂或存在特殊字符，导致 LLM 生成的 search pattern 不合法或不存在
  4. LLM 自身的幻觉导致 search pattern 不存在或格式错误

缓解方式：

  1. 告诉 AI 使用 shell 命令或脚本进行文件编辑
  2. 让 AI 生成正确的或更加准确的搜索 Pattern 后重试
  3. 让 AI 说出它的思路，人工编辑文件

Improperly formed request #

通常是由于 LLM 的幻觉导致，可以告诉 AI “重试” 或者 “继续” 或者 “go on”，如果多次重试仍然失败，可以尝试开启一个新会话。

An unexpected error occurred #

通常是网络不稳定导致，也可能是登录过期。可以告诉 AI “重试” 或者 “继续” 或者 “go on”，如果多次重试仍然失败，可以尝试重新开始会话，重新登录，或排查网络连接。

可以参考下文查看日志来进一步确定问题原因。

Dispatch failure #

通常是网络不稳定导致，可以告诉 AI “重试” 或者 “继续” 或者 “go on”，如果多次重试仍然失败，可以尝试重新开始会话，或排查网络连接。

无法自动补全 #

首先，确认自动补全是否开启。确认的方法为：在 VSCode 或 JetBrains IDE 的底部栏会有 Amazon Q 的按钮，点击后可以确认 Auto Suggestion 是否为启用的状态。

如果确认自动补全已经开启，仍然无法使用，请查看日志，在日志中搜索 GenerateCompletion，查看相关报错。以下是 JetBrains 中的报错示例：

2025-09-25 11:02:10,730 [1391649]   INFO - software.aws.toolkits.jetbrains.services.amazonq.lsp.AmazonQLanguageClientImpl - [2025-09-25T03:02:10.727Z] lserver: GenerateCompletion activity:
@@request metadata@@
    "endpoint": https://codewhisperer.us-east-1.amazonaws.com/,
    "predictionType": Not specified (COMPLETIONS),
    "filename": xxx.java,
    "leftContextLength": 412,
    rightContextLength: 34,
    "language": java,
    "supplementalContextCount": 3,
    "request.nextToken": xxx,
    "recentEdits": No recent edits
error: read ECONNRESET
2025-09-25 11:02:10,730 [1391649]   INFO - software.aws.toolkits.jetbrains.services.amazonq.lsp.AmazonQLanguageClientImpl - [2025-09-25T03:02:10.727Z] lserver: Recommendation failure: TimeoutError: read ECONNRESET

如果是上述网络相关报错，请确保您本地可以正常访问 https://codewhisperer.us-east-1.amazonaws.com/

Inline Chat 生成代码异常 #

Inline Chat 功能 （快捷键：Cmd+I 或 Ctrl+I）需要选中代码后使用，AI 生成的代码会覆盖选中的代码。所以此功能主要用来定点编辑选中的代码，除此之外的场景建议使用聊天面板来进行交互。

如果不选中代码，直接使用快捷键触发 Inline Chat，那么 AI 很可能在光标处插入一个全新的文件。仅适合在创建新文件的时候使用。

除此之外，Inline Chat 默认情况下包含的上下文远少于普通聊天面板，所以仅建议进行上下文不太相关的编辑。

Inline Chat 在编辑完毕后，需要点击 Accept / Reject （或使用快捷键）进行接受/拒绝，否则无法进行下一次的 Inline Chat 交互。

无法启动 Language Server #

IDE 插件会启动一个 Language Server 进程来解析工作目录下的源代码。Language Server 会被下载并保存在用户目录的 AppData\Local\aws\toolkits\language-servers 目录下。

如果无法启动 Language Server，可尝试清空如上目录以便重新下载 Language Server。下载时会请求 https://aws-language-servers.us-east-1.amazonaws.com 的子路径，请确保您的网络可以访问此 URL

另外，由于 Language Server 是一个 NodeJS 进程，请确保上述目录的父级目录中不存在 package.json 文件。特别是要检查一下用户目录下是否存在 package.json 文件，如果有，请删除后再尝试重启 IDE 插件。

连接超时/连接被重置/ConnectionTimeout/ConnectionReset #

请参考 官方文档验证您能否【从 IDE 中】访问这些 URL 地址。验证方法：

  1. 打开 IDE 的集成终端（VSCode 可以使用快捷键 Ctrl+J 展开底部面板后选择终端，JetBrains IDE 可以在左下角的按钮中展开终端）
  2. 对于 Windows 用户，确保使用 cmd 而非 powershell
  3. 执行 curl <URL>，如 curl https://codewhisperer.us-east-1.amazonaws.com 来验证网络是否通畅。如果报错 connection timeout 则说明网络不通畅，如果报错 404/401 等正常的 HTTP 报错，则说明服务器可达，网络没问题。

如果网络确实不通畅，请检查 IDE 的网络代理设置、系统网络代理设置等网络配置

CLI 常见错误 #

无法升级 #

配置 VPC Endpoint 后，可能无法使用 q update 进行 CLI 的升级。这是因为升级时需要访问 desktop-release.q.us-east-1.amazonaws.com ，它是 Q 的 VPC Endpoint 的子域名。如果您需要升级，可以参考 此文档，从公网下载 zip 安装包后手动安装。

byte index is not a char boundary #

Q CLI 使用 Rust 语言编写，对 UTF-8 字符串的合法性有严格要求。此报错说明 Q CLI 处理了非法的 UTF-8 字符串，请检查本地文件是否包含非法 UTF-8 字符

Prompt 如何定义和传递参数 #

目前只有 MCP Prompt 支持参数。可以使用 shinkuro 或类似的 MCP 服务器，把文件提示词转为 MCP 提示词，从而支持参数

问题上报 #

如何在 Visual Studio Code 查看插件的日志？ #

如果是偶发性的问题（例如，AI 幻觉、命令参数不正确）是正常现象。如果 Amazon Q Developer 在某个问题上能稳定复现，建议获取 Amazon Q Logs 提供给 AWS Support 或者 AWS 解决方案架构师。

日志获取方式 1：

登录后，聊天窗口右上角有导出日志的按钮。

日志获取方式 2（适用于无法登陆的场景）：

  1. 打开 Visual Studio Code 的 OUTPUT。通过点击菜单栏的 View，再点击 Output 打开面板
  2. 下拉选择 Amazon Q Logs
  3. 点击齿轮按钮，选择 Trace 类型的日志

注意: 您只有打开 Trace 日志后，再操作 Amazon Q Developer 才会记录 Trace 级别的日志。

如何在 JetBrains IDE 中查看插件日志？ #

如果是偶发性的问题（例如，AI 幻觉、命令参数不正确）是正常现象。如果 Amazon Q Developer 在某个问题上能稳定复现，建议获取 Amazon Q Logs 提供给 AWS Support 或者 AWS 解决方案架构师。

以下以 JetBrains IntelliJ IDEA 为例：

日志获取方式 1：

登录后，聊天窗口右上角有导出日志的按钮。此方式会导出一个 zip 格式的压缩包，解压后请关注里面的 idea.log 文件

日志获取方式 2（适用于无法登陆的场景）：

顶部菜单 → Help → Show Log in Explorer/Finder → idea.log

除此之外，也可以使用 “Collect Logs and Diagnostic Data” 收集更详细的信息。

如何阅读 JetBrains IDE 插件日志 #

以下以 JetBrains IntelliJ IDEA 为例：

通过上文导出的 idea.log 日志文件包含了所有的日志，请搜索 software.aws.toolkits.jetbrains.services.amazonq 查看与 Amazon Q 插件相关的日志行，关注其中的报错信息（如 ERROR, WARN）

如何查看 Q CLI 日志 #

方法 1（推荐）

最新版本 Q CLI 可以使用 /logdump 命令把日志保存为一个 ZIP 文件。

方法 2

您可以使用 -vvv 参数启动 Q CLI 来生成日志，如 q -vvv chat。

不同操作系统的日志存储路径不同：

  • MacOS
    • $TMPDIR/qlog/
  • Linux
    • $XDG_RUNTIME_DIR/qlog/
    • $TMPDIR/qlog/
    • /tmp/qlog/
  • Windows
    • %TEMP%\qlog\

参考 官方文档。

浏览器登录页面无法加载，白屏，如何反馈 #

如果您为浏览器配置了网络代理，或配置了系统代理，请尝试关闭/开启代理后重试。

如果上述无法解决问题，请使用快捷键 F12 打开浏览器控制台，查看是否有网络请求失败，是哪些域名或 URL 请求失败，以及控制台中的报错信息有哪些。

将上述代理信息、请求信息、报错信息与操作系统信息提供给 AWS Support 或者 AWS 解决方案架构师

我有 IDE Plugin 问题希望上报给产品团队，请问需要提供哪些信息？ #

为加速我们排查您遇到的问题，我们建议您复现问题，并提供如下信息给 AWS Support 或者 AWS 解决方案架构师：

必须项：

  1. 日志信息（建议去除敏感信息）。请参考上文获取 IDE 插件中的日志
  2. 插件的版本信息，在 IDE 的插件面板中可以查看当前版本。如果不是最新版，您可以尝试通过插件市场升级到最新版后，再看下问题是否还存在
  3. IDE 的版本信息，在 IDE 的帮助菜单中可以查看当前 IDE 的版本
  4. 操作系统版本信息，如 Windows 11
  5. 问题描述，以及已经进行过哪些排查

可选项： 问题的视频或者截图（如您能提供问题的视频或者截图将有助于我们排查问题）

我有 Q CLI 问题希望上报给产品团队，请问需要提供哪些信息？ #

为加速我们排查您遇到的问题，我们建议您复现问题，并提供如下信息给 AWS Support 或者 AWS 解决方案架构师：

必须项：

  1. 日志信息（建议去除敏感信息）。请参考上文获取 CLI 的日志
  2. CLI 的版本信息，使用 q --version 可以查看当前版本。如果不是最新版，您可以尝试执行 q update 升级到最新版后，再看下问题是否还存在
  3. 操作系统版本信息，如 Windows 11
  4. 问题描述，以及已经进行过哪些排查

可选项： 问题的视频或者截图（如您能提供问题的视频或者截图将有助于我们排查问题）