Documentation
This guide helps you resolve common issues with Kiro, including shell integration and MCP server connection problems.
On macOS, you may encounter this error when trying to open Kiro:
Kiro is damaged and can't be opened. You should move it to the Trash.
This pop-up is due to a false positive in macOS security features.
To resolve this error:
Kiro.app to your desktop, and then drag it from your desktop to the Applications folder.sudo xattr -d com.apple.quarantine /Applications/Kiro.app
If while authenticating with Kiro you are not redirected to the browser, try these platform-specific solutions:
Run Kiro with logging enabled to identify potential issues:
C:\path\to\app.exe --enable-logging
Use the developer tools to diagnose the issue:
ioreg commandioreg is included in your PATH variable:
echo $PATH which ioreg
ioreg is missing, it's typically located at /usr/sbin/ioregIf you see an error There was an error signing you in when attempting to authenticate with Identity Center, ensure you have a valid Q Developer Pro subscription. You need an active Pro subscription to use Identity Center authentication with Kiro. Here is a guide on how to view your subscription status and upgrade to Pro.
If you're unable to sign in with Identity Center despite having valid credentials, this may be due to regional limitations. Kiro defaults to the US East (N. Virginia) region for Identity Center authentication. If you have a Q Developer profile in a different region, you won't be able to sign in with Identity Center.
As an alternative, use a different login method such as Builder ID or social providers such as Google or GitHub. We're working on addressing this regional limitation in future releases.
Identity Center sessions have a default timeout of 8 hours, which means you'll need to re-authenticate periodically. To extend session duration, administrators can configure longer session timeouts. For detailed configuration instructions, see the AWS documentation on configuring user session duration.
Shell integration connects Kiro to your terminal, enabling automatic command execution and result processing. Without it, you'll need to manually copy-paste terminal outputs.
Cmd + Shift + P / Ctrl + Shift + P) → Kiro: Check for UpdatesCmd + Shift + P / Ctrl + Shift + P) → Kiro: Enable Shell IntegrationIf automatic setup fails, add to your shell config:
Zsh (~/.zshrc):
[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path zsh)"
Bash (~/.bashrc):
[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path bash)"
Fish (~/.config/fish/config.fish):
string match -q "$TERM_PROGRAM" "kiro" and . (kiro --locate-shell-integration-path fish)
PowerShell ($Profile):
if ($env:TERM_PROGRAM -eq "kiro") { . "$(kiro --locate-shell-integration-path pwsh)" }
If Kiro is unable to read terminal output, gets stuck in Working... status, or you see strange characters and formatting issues, this is typically caused by shell customizations that interfere with terminal integration. Common culprits include customizations like bash-it on bash or Oh My Posh on zsh, and themes such as Powerlevel10k/9k.
If you're using Powerlevel10k theme, add this line to your .p10k.zsh file:
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true
Alternatively, you can also disable these customizations when running in Kiro.
zsh (~/.zshrc):
if [[ "$TERM_PROGRAM" == "kiro" ]]; then # Leave empty else # Your themes or customizations ZSH_THEME="powerlevel10k/powerlevel10k" fi
If you're using Fish shell and experiencing terminal output issues, you may need to manually add Kiro to the existing shell integration script. The Fish shell integration file is located at:
/Applications/Kiro.app/Contents/Resources/app/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration.fish
By default, the integration script only checks for "vscode":
status is-interactive and string match --quiet "$TERM_PROGRAM" "vscode" and ! set --query VSCODE_SHELL_INTEGRATION or exit
You need to update it to include "kiro" as well:
status is-interactive and string match --quiet "$TERM_PROGRAM" "vscode" "kiro" and ! set --query VSCODE_SHELL_INTEGRATION or exit
On Windows if you experience this error:
Updates are disabled because you are running the user-scope installation of Kiro as Administrator. This occurs as Kiro does not support system-level installation, which requires administrator privileges.
To remove run as administrator, you can:
Show more optionsPropertiesCompatibility tabRun this program as an administrator checkboxApply and then OK to save the changesAfter completing these steps, Kiro should be able to update normally.
In PowerShell 7+ set execution policy:
Check current policy:
Get-ExecutionPolicy
Set execution policy:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
If you use OneDrive on Windows, your desktop path might cause issues:
mklink /J "C:\Users\<username>\Desktop" "C:\Users\<username>\OneDrive\Desktop"
If you're having trouble connecting to MCP servers:
Check server status:
Verify configuration:
Check prerequisites:
Review logs:
Connection failures:
# Verify uv installation uv --version # Verify Python version python --version # Test server directly uvx awslabs.aws-documentation-mcp-server@latest --help
Search or read failures:
Authentication errors:
Rate limiting issues:
If you've tried the troubleshooting steps above and still need assistance:
Troubleshooting