Kiro IDE 常見問題
全部開啟請嘗試重啓 IDE 並檢查系統網路狀態
GitHub issue: https://github.com/kirodotdev/Kiro/issues/1147
請升級至最新版 IDE，並在新創建的會話中交互。舊版本的 Kiro 創建的聊天會話可能存在此問題。
- 確保升級到 v0.6.0 版本以上
- 確保設置中 Codebase Indexing 已禁用
原因：Codebase Indexing 功能會對專案文件進行索引，可能會佔用較多的 CPU 和記憶體資源，特別在項目較大時，資源佔用尤爲明顯。如果不需要該功能，建議禁用以提升性能。v0.6.0 版本默認禁用了此功能，並在設置中提供了開關選項。
這兩個選項需要在設置中啓用 Codebase Indexing 才能啟用。但是需要注意：啓用 Codebase Indexing 後可能會導致 CPU/記憶體佔用過高。Agentic Coding 時代基於 本地 RAG 的 Codebase indexing 不再是必選項，它會消耗額外性能（CPU 和記憶體），召回效果不穩定，並且可以使用 fs_search tool 或類似的 CLI 代替，甚至效果更好。所以並不建議使用
建議的解決方案:
- 直接通過聊天告訴 AI “在程式庫中搜索 XXX”，利用 fs_search tool 進行搜索
- 此問題在 GitHub issue 中有跟進
報錯：Improperly formed request 或 An unexpected 錯誤 occurred
通常是 MCP Tool 的描述格式不規範，特別是 input_schema 字段，需要嚴格保證爲合法的 JSON 架構。請檢查您的 MCP Server是否爲最新版本
預設情況下 Kiro 的自動代碼補全就是啓用的狀態。可以點擊底部欄的 Autocomplete 按鈕來查看和修改自動補全的設置。
目前在版本管理界面的 🪄按鈕無法自定義語言，只能生成英文，也不會受到 Steering 文件影響。
緩解的方案是：通過聊天面板，告訴 Kiro：“提交當前修改，使用中文 Commit Message”，讓 Kiro 通過 Git 命令行實現提交。
爲了讓使用更加順暢，您可以創建一個手動觸發的 Agent Hooks，參考內容(.kiro\hooks\manual-git-commit.kiro.hook)：
{
"enabled": true,
"name": "Git提交",
"description": "手動觸發的鈎子，用於將當前修改提交到Git，使用中文提交信息",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "查看當前的git修改，使用git status和git diff命令。創建一個有意義的中文提交資訊來描述這些修改。然後執行：git add -A && git commit -m \"[你的中文提交信息]\"。提交信息應該清晰、簡潔，遵循良好的提交資訊規範，完全使用中文書寫。"
}
}
這樣，當需要提交的時候，點擊觸發 Agent Hook 即可。
參考下文 登录退出异常，排查系統瀏覽器是否可以被正常喚起，以及 callback監聽埠是否被佔用
現象：使用 fsReplace / fsWrite / fsAppend 等類似工具編輯文件失敗
原理: Agent 在編輯文件時會先搜索一個模式，然後替換它爲新的程式碼區塊。如果這個 模式在文件中有多個匹配或者沒有匹配，agent 就會無法替換代程式碼區塊從而報錯。
通常導致這些問題的原因包括：
- 文件被人類或其他工具修改後沒有被 AI 重新讀取
- 文件太長，導致簡單的模式在同一個文件中出現多次
- 需要搜索的模式過於複雜或存在特殊字符，導致 LLM 生成的 搜尋模式不合法或不存在
- LLM 自身的幻覺導致搜尋模式不存在或格式錯誤
緩解方式：
# 錯誤資訊
"Shell 集成不可用"
# 嘗試自動修復
1. 按 Cmd/Ctrl+Shift+P 打開命令面板
2. 執行 "Kiro: Enable Shell Integration"
3. 重啓 Kiro
# 手動修復方法
```sh
# Zsh（macOS 預設）
echo '[["$TERM_PROGRAM" == "kiro"]] && . "$(Kiro --locate-Shell-integration-path zsh)"' >> ~/.zshrc
source ~/.zshrc
# Bash
echo '[["$TERM_PROGRAM" == "kiro"]] && . "$(Kiro --locate-Shell-integration-path bash)"' >> ~/.bashrc
source ~/.bashrc
# Fish
echo 'string 匹配 -q "$TERM_PROGRAM" "Kiro"' >> ~/.config/fish/config.fish
echo 'and . (Kiro --locate-Shell-integration-path fish)' >> ~/.config/fish/config.fis
# PowerShell（Windows）
Add-Content $PROFILE 'if ($env:TERM_PROGRAM -eq "Kiro") { . "$(Kiro --locate-Shell-integration-path pwsh)" }'
- 沒有 Q Developer Pro 訂閱 → 請使用 Builder ID 或社交賬號登錄
- 區域設置錯誤 → 請確認公司使用的 IAM Identity Center 的區域（不是 Amazon Q Developer 訂閱的區域）。
- Start URL 錯誤 → 請聯繫 IT 部門確認正確的 URL。
# 常見錯誤及解決方法
# Error: Command not found
→ 未安裝必要的工具
# 針對 AWS Docs Server
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
uv Python install 3.10
```
# 針對 Error: Timeout
→ 增加超時時間
“timeout”: 30000 # 30 秒
# 針對 Error: Permission denied
→ 檢查 API 密鑰和認證信息
```sh
echo $GITHUB_TOKEN
echo $BRAVE_API_KEY
```
# 調用測試方法
1.打開 Output → “Kiro - MCP Logs” 查看日誌
2.通過 /mcp 命令檢查 server狀態
3.手動執行 server 命令進行測試
# 確認 .gitignore 的影響
cat .gitignore
# 確認 Kiro 的配置
{
“fileFiltering”: {
“respectGitIgnore”: false # 臨時禁用
}
}
# 對於大文件的情況
“@large-file.log:1000-2000” 指定行號範圍部分讀取
以下是 Windows 環境排查登錄退出異常的方法，Mac/Linux 用戶可以參考流程。
## 1) 先用“官方建議”的方式打開日志
1. 以管理员打開CMD。
2. 運行（按你的安裝路徑替換）：
```sh
"%LocalAppData%\Programs\Kiro\Kiro.exe" --enable-日誌記錄
```
這是 Kiro 文件給 Windows 的排查方式，能看到認證時的錯誤信息（比如權限或 callback失敗）
---
## 2) 快速自檢：默認瀏覽器能否被系統調用
在同一個 CMD 內測試：
start "" "https://example.com"
能打開：預設瀏覽器關聯正常。
打不開：去設定 → 應用 → 預設應用，把 HTTPS 關聯到 Edge/Chrome，然後再試一次。
>Kiro 登錄會 “把你帶到默認瀏覽器完成驗證”。如果系統層面打不開瀏覽器，Kiro 自然不會彈。
---
## 3) 檢查 callback 監聽埠（重點：localhost:3128）
Kiro 登錄會在本地起一個 callback監聽，常見是 http://127.0.0.1:3128；瀏覽器登錄成功後會重定向回到這裡。若這個監聽埠被佔用/被系統保留，瀏覽器就算打開了也回不來，或者根本起不來登錄流程。
看有沒有程式佔用 3128：
```sh
netstat -ano -p tcp | findstr :3128
```
- 如果看到 `LISTENING/ESTABLISHED`，記下 PID，在“任務管理器”結束它（或 taskkill /PID <pid> /F）。
- 常見佔用者：代理/抓包工具（Fiddler、CNTLM、Zscaler 等）。
看 3128 是否被 Windows 保留為排除監聽埠（Excluded Port Range）：
```sh
netsh int ipv4 show excludedportrange protocol=tcp
```
- 如果輸出範圍里包含 3128，則該監聽埠不可綁定，Kiro 無法啓動 callback服務（這會導致“打不開瀏覽器/卡登錄”）。
釋放 3128 的排除佔位（需要管理員 CMD，謹慎執行）：
```sh
netsh int ipv4 delete excludedportrange protocol=tcp startport=3128 numberofports=1
```
有用戶在 Windows 上遇到“登錄不彈/不回跳”，確認與 3128 監聽埠衝突/被系統保留有關；釋放佔位或避免衝突即可恢復。
如果你改動過系統動態監聽埠範圍，請記錄原值；Windows 默認動態監聽埠一般為 start=49152 num=16384，可用 `netsh int ipv4 show dynamicport tcp 查看，必要時用 `netsh int ipv4 set dynamicport tcp start=49152 num=16384` 恢復。
---
## 4) 清理“對登錄有影響”的快取
## Windows
先完全退出 Kiro（或 taskkill /IM Kiro.exe /F），然後刪除：
```sh
rmdir /S /Q "%AppData%\Kiro"
rmdir /S /Q "%UserProfile%\.Kiro"
rmdir /S /Q "%UserProfile%\.AWS\sso\快取"
rmdir /S /Q "%LocalAppData%\Kiro"
```
這些是 Windows 上對應的本地狀態目錄；清理後常能恢復“卡住等待認證提供方”的問題。
再啓動 Kiro 重試登錄。
## MacOS
`rm ~/.aws/sso/cache/kiro-auth-token.json`
再啓動 Kiro 重試登錄。
---
5) 如果你用的是 IAM Identity Center 登錄
- 必須有 Q Developer Pro 訂閱才可用 Identity Center 登錄方式；否則會報“簽入錯誤”。[Kiro](https://kiro.dev/docs/reference/troubleshooting/)
- Kiro 目前預設使用 us-east-1 做 Identity Center 登錄；如果你的目錄/配置在別的 Region，會導致無法登錄。此時可暫時改用 Builder ID / GitHub / Google 登錄，或把目錄配到該 Region。
IAM Identity Center 的常見登錄/會話問題可參考官方故障排查
## 成功後的驗證
- 瀏覽器彈出後，完成授權應自動回到 Kiro；若瀏覽器地址欄出現 http://127.0.0.1:3128/...，說明callback監聽埠正常
出現此類錯誤有多種可能性，請按照如下步驟進行排查：
1. 確認登錄 StartURL 和 Region 是否選擇正確。如有需要，請聯繫您的管理員獲取正確的 StartURL 和 Region。
2. 如果報錯訊息是：“有些內容無法計算：我們無法驗證您的登錄憑證，請重試”，說明您的用戶名或密碼填寫有誤。
3. 如果上述訊息無誤，請檢查您的系統時間是否正確。
請刪除此文件：`~/.aws/sso/cache/kiro-auth-token.json`
通常是網路切換或者不穩定導致，例如您一開始沒有使用 VPN，突然撥了 VPN。解決方案如下：
1. 嘗試告訴 AI “繼續” 或者 “Go on”。
2. 如果您不需要當前會話的上下文，嘗試重新開始會話。
3. 如果您需要當前會話的上下文，嘗試重啓 Kiro 後，在當前會話輸入 “繼續” 或者 “Go on”。
An unexpected error occurred
“An unexpected error occurred, please 重試.” 是我們在遇到未被識別或未被顯式處理的異常時統一返回的兜底錯誤信息。這類錯誤可能由多種原因引起，在某些邊界/異常狀態下處理不完善。包括但不侷限於以下幾類：
1. 圖片處理缺陷
- 在發送某些特定類型的圖片時可以復現，例如將一條 Slack 消息與用戶圖片一起復制粘貼發送。日誌裏例如 “TypeError: The first argument must be of type string or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object. Received undefined”。
- 系統無法處理 HTTP/HTTPS 格式的圖片連結，只能識別 Base64 編碼格式
2. MCP 工具
- 如果 MCP tool 的描述超過 10240 字符會引發錯誤
- 有些 MCP 工具（例如 “pdf-reader-mcp”）生成了不正確的 input 架構 （malformed 架構，Improperly formed request）給 Kiro
3. 網路連接問題
- 關閉 WiFi 或網路連接中斷時發送請求會導致相同錯誤
- 使用 VPN 會導致該問題，許多 VPN 不穩定。
對於以上錯誤，一旦遇到建議優先排查
通常是網路切換或者不穩定導致，例如您一開始沒有使用 VPN，突然撥了 VPN。解決方案如下：
1. 嘗試告訴 AI “繼續” 或者 “Go on”。
2. 如果您不需要當前會話的上下文，嘗試重新開始會話。
3. 如果您需要當前會話的上下文，嘗試重啓 Kiro 後，在當前會話輸入 “繼續” 或者 “Go on”。
使用 Amazon Q Developer 訂閱登錄 Kiro 無法查看用量，請升級到 Kiro 訂閱
通常是網路切換或者不穩定導致
# 查看 Kiro 各服務的日誌
View -> Output
# 啓用 Kiro 日誌
kiro –enable-logging
# 打開開發者工具
Help → Toggle Developer Tools → Console
# 查看當前設定
cat ~/.kiro/settings.json cat .kiro/settings.json
# 查看記憶體（上下文）內容
/memory show
# 手動測試 MCP 服務器
# 以 GitHub 服務器為例
npx @modelcontextprotocol/server-github
# 檢查網路問題
curl -I https://api.github.com curl -I https://kiro.dev
如果以上方法無法使 Kiro 正常工作，也可以嘗試徹底清除本地文件後重新安裝 Kiro。
Windows
- 停止所有正在運行的 Kiro 程序
- taskkill /f /im Kiro.exe
- 卸載（如果使用的是用戶級安裝）
- rmdir /s /q “%LOCALAPPDATA%”
- 卸載（如果使用的是系統級安裝）
- if exist “%PROGRAMFILES%” rmdir /s /q “%PROGRAMFILES%”
- 刪除所有用戶數據和設置
- rmdir /s /q “%APPDATA%”
- 刪除插件
- rmdir /s /q “%USERPROFILE%.kiro”
- 從 Program Files (x86) 中刪除
- if exist “%PROGRAMFILES(X86)%” rmdir /s /q “%PROGRAMFILES(X86)%”
- 從桌面圖標和開始菜單中刪除
- if exist “%USERPROFILE%.lnk” del /q “%USERPROFILE%.lnk”
- if exist “%APPDATA%Menu” rmdir /s /q “%APPDATA%Menu”
MacOS
- 刪除 ~/.kiro
- 刪除 Library/Application Support/Kiro
如果是偶發性的問題（例如，AI 幻覺、命令參數不正確）是正常現象。如果 Kiro 在某個問題上能穩定復現，建議獲取 Logs 提供給 AWS Support 或者 AWS 解決方案架構師。我們建議您至少提供以下兩種日誌：
Agent 日誌
1. 打開 Kiro 的 OUTPUT。通過點擊菜單欄的 View，再點擊 Output 打開面板
2. 下拉選擇 Kiro 相關的日誌，如 Kiro Logs。您可以看下哪個日誌裡面有報錯
3. 點擊齒輪按鈕，選擇 Trace 類型的日誌
4. 可以點擊選項按鈕，在編輯器中打開日誌以便複製和保存
客戶端日誌
1. 頂部欄點擊 Help -> Toggle Developer Tools 打開開發者工具
2. 點擊 Console 面板即可查看日誌。
日誌收集完畢後，點擊 Kiro 底部欄的 “Report issue” 按鈕進行問題上傳。