Documentation

Troubleshooting

This guide helps you resolve common issues with Kiro, including shell integration and MCP server connection problems.

Copied!Kiro Installation Issues

Copied!Kiro is damaged and can't be opened

Issue: 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.

Possible cause: This pop-up is due to a false positive in macOS security features.

Recommended solutions: Here are several solutions to resolve this error, listed in order of simplicity.

  • Go to System Settings → Privacy & Security and click Allow or Open anyway for Kiro.
  • Drag Kiro.app to your desktop, and then drag it from your desktop to the Applications folder.
  • Restart your computer.
  • Open your terminal and run: 
    sudo xattr -d com.apple.quarantine /Applications/Kiro.app

Copied!Authentication Issues

Copied!Browser Redirect Failures During Authentication

If while authenticating with Kiro you are not redirected to the browser, try these platform-specific solutions:

Copied!Windows

Run Kiro with logging enabled to identify potential issues:

  1. Open Command Prompt as administrator
  2. Run the following command (replace with your actual Kiro installation path): 
    C:\path\to\app.exe --enable-logging
  3. Check the logs for any errors
  4. If you see access denied errors, ensure your user has administrator permissions to run the app

Copied!macOS

Use the developer tools to diagnose the issue:

  1. Open Kiro
  2. Go to Help → Toggle Developer Tools
  3. Navigate to the Console tab
  4. Observe any errors reported during the sign-in process
  5. If the error indicates a missing dependency, ensure it's available in your PATH
    • One common issue is the missing ioreg command
    • Verify ioreg is included in your PATH variable:
      bash
      echo $PATH
which ioreg
    • If ioreg is missing, it's typically located at /usr/sbin/ioreg

Copied!AWS IAM Identity Center Issues

Copied!Q Developer Pro Subscription Required

If 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.

Copied!Regional Limitations for Q Developer Profiles

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.

Copied!Session Duration and Timeouts

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.

Copied!Shell Integration Issues

Copied!What is Shell Integration?

Shell integration connects Kiro directly with your terminal, allowing you to work more efficiently with command-line tools. It gives Kiro the ability to see terminal activity and interact with it.

Without shell integration, you need to manually copy-paste terminal outputs to Kiro. With it enabled, Kiro can:

  • Run terminal commands and process the results automatically
  • Monitor development servers and help fix problems in real time
  • Understand your project environment through command outputs
  • Complete tasks that require terminal interaction

Shell integration works like having a pair programmer who can see your terminal and assist you immediately.

Copied!Fixing "Shell Integration Unavailable" Error

If you encounter this error, follow these steps:

Copied!Step 1: Update Your IDE

Make sure you're using the latest version:

  1. Open the Command Palette:
    • Mac: Press Cmd + Shift + P
    • Windows/Linux: Press Ctrl + Shift + P
  2. Type Kiro: Check for Updates and select it
  3. Restart your IDE after updating

Copied!Step 2: Configure the Shell

  1. Open the Command Palette (Cmd + Shift + P or Ctrl + Shift + P)
  2. Type Kiro: Enable Shell Integration and select it
  3. Kiro will configure the following shells:
    • zsh
    • bash
    • fish
    • PowerShell

Copied!Step 3: Restart Your IDE

  1. Quit the application completely
  2. Reopen Kiro and start a new chat session

Copied!Manual Shell Integration Installation

If automatic shell integration fails, install it manually:

Copied!For Zsh Users

bash
# Add to ~/.zshrc
[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path zsh)"

Copied!For Bash Users

bash
# Add to ~/.bashrc
[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path bash)"

Copied!For Fish Users

bash
# Open the  file
kiro $__fish_config_dir/config.fish

# Add to config.fish
string match -q "$TERM_PROGRAM" "kiro"
and . (kiro --locate-shell-integration-path fish)

Copied!For PowerShell Users

bash
# Open the file
kiro $Profile

# Add to your PowerShell profile
if ($env:TERM_PROGRAM -eq "kiro") { . "$(code --locate-shell-integration-path pwsh)" }

Copied!Windows-Specific Issues

Copied!PowerShell Configuration

If you prefer PowerShell:

  1. Use PowerShell 7+ for best compatibility

  2. Adjust execution policies if needed:

    powershell
    # Check current policy
Get-ExecutionPolicy

# Set to RemoteSigned (recommended for development)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Copied!Understanding PowerShell Execution Policies

PowerShell uses execution policies to determine which scripts can run on your system:

PolicyDescription
RestrictedBlocks all scripts
AllSignedRuns scripts signed by trusted publishers
RemoteSignedRuns local scripts and signed remote scripts
UnrestrictedRuns all scripts (not recommended)

For development work, RemoteSigned provides a good balance of security and functionality.

Copied!OneDrive Path Issues

If you use OneDrive on Windows, your desktop path might cause issues:

  1. Launch Command Prompt as administrator
  2. Create a symbolic link: 
    mklink /J "C:\Users\<username>\Desktop" "C:\Users\<username>\OneDrive\Desktop"
  3. Restart your IDE

Copied!Unusual Terminal Output

If you see strange characters, escape sequences, or formatting issues:

  1. Check for terminal customization tools that might conflict:

    • Oh My Zsh themes
    • Starship prompt
    • Custom PS1 configurations
    • PowerShell prompt customizations

  2. Temporarily disable these tools in your shell configuration file:

    bash
    # For Zsh, comment out in ~/.zshrc
# source ~/.p10k.zsh

  3. For PowerShell users, check your profile:

    powershell
    # View your profile location
echo $PROFILE

# Edit your profile and comment out prompt customizations

Copied!MCP Server Connection Issues

Copied!Common MCP Connection Problems

If you're having trouble connecting to MCP servers:

  1. Check server status:

    • Open the Kiro panel and navigate to the MCP servers tab
    • Check the connection status indicator for your server

  2. Verify configuration:

    • Ensure your MCP configuration file has the correct syntax
    • Check that the server command and arguments are correct

  3. Check prerequisites:

    • Make sure all required dependencies are installed
    • For AWS Documentation server, verify Python 3.10+ and uv are installed

  4. Review logs:

    • Open the Output panel in Kiro
    • Select "Kiro - MCP Logs" from the dropdown
    • Look for specific error messages

Copied!Fixing Specific MCP Issues

Copied!AWS Documentation Server

  1. Connection failures:

    bash
    # Verify uv installation
uv --version

# Verify Python version
python --version

# Test server directly
uvx awslabs.aws-documentation-mcp-server@latest --help

  2. Search or read failures:

    • Check your internet connection
    • Verify the URL format for documentation pages
    • Try with a simpler search query

Copied!GitHub MCP Server

  1. Authentication errors:

    • Verify your personal access token is valid
    • Ensure the token has the required scopes (repo, user)
    • Generate a new token if necessary

  2. Rate limiting issues:

    • GitHub API has usage limits
    • Check the rate limit status in the MCP logs
    • Consider using a token with higher rate limits

Copied!Getting Help

If you've tried the troubleshooting steps above and still need assistance:

  1. Check our FAQ for common questions
  2. Join our community Discord for help
  3. Submit an issue on GitHub with:
    • Your operating system details
    • Kiro version
    • Steps you've already tried
    • Error messages (if any)
Page updated: July 14, 2025