Troubleshooting

This page covers installation issues, network connectivity, authentication, shell integration, and MCP server problems. For post-upgrade migration steps (sessions, hooks, permissions), see What's new in IDE 1.0.

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:

• 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
  

If Kiro works for some users in your organization but not others, the issue is likely related to network configurations specific to the affected users. A common cause is TLS inspection — corporate firewalls performing TLS inspection may block or interfere with connections to Kiro endpoints.

• Kiro IDE shows "No profiles available" after successful sign-in
• Client logs show Failed to retrieve profiles {"error":""} (empty error string indicates a network-level failure)
• Sign-in completes but chat and code assistance are unavailable

Affected users can test connectivity directly:

curl -v https://runtime.us-east-1.kiro.dev
curl -v https://management.us-east-1.kiro.dev

A successful TLS handshake (even with an HTTP error response) confirms network connectivity. A connection timeout or TLS error indicates a firewall or proxy issue.

If these commands fail, review the firewall allowlist and work with your network team to ensure the required endpoints are reachable from the affected users' network path.

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:

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

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

If you see an error There was an error signing you in when attempting to authenticate with Identity Center, ensure your subscription status is active. IAM Identity Center authentication requires an active subscription. Kiro profiles are currently supported in the US East (N. Virginia) and Europe (Frankfurt) regions.

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.

Kiro IDE generates detailed logs that can help you diagnose and resolve issues. The logs are stored in the following locations.

• Windows: %APPDATA%\Kiro\logs\ (default: C:\Users\<Username>\AppData\Roaming\Kiro\logs\)
• macOS: ~/Library/Application Support/Kiro/logs/
• Linux: $XDG_CONFIG_HOME/Kiro/logs/ (default: ~/.config/Kiro/logs/)

If you cannot sign in to Kiro, collect the logs directly from the appropriate location listed above. If you are signed in and can use the IDE, you can also export the logs as follows:

1. Open the Command Palette and run Developer: Export Logs....
2. Select the check boxes for Kiro Logs and KiroLLMLogs, and then select OK.
3. In the save dialog, choose where to save the file.

When a workspace is open, you can also collect a debug log archive by running Kiro: Create Debug Log Zip from the Command Palette.

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.

1. Update Kiro: Command Palette (Cmd + Shift + P / Ctrl + Shift + P) → Kiro: Check for Updates
2. Enable Integration: Command Palette (Cmd + Shift + P / Ctrl + Shift + P) → Kiro: Enable Shell Integration
3. Restart: Quit and reopen Kiro

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

1. Right-click on the Kiro icon
2. Select Show more options
3. Select Properties
4. Navigate to the Compatibility tab
5. Uncheck the Run this program as an administrator checkbox
6. Select Apply and then OK to save the changes

After 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:

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

On Ubuntu 24.04 and later, Kiro may not open at all, or exit as soon as you start it. If you run the kiro binary from a terminal, you see an error like this:

The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /path/to/kiro/chrome-sandbox is owned by root and has mode 4755.

Ubuntu 24.04 blocks apps from creating user namespaces unless an AppArmor profile allows it. Kiro's sandbox needs them, so without a profile it falls back to the chrome-sandbox helper, which only works if it's owned by root.

Starting with Kiro 1.4.0, the .deb package installs an AppArmor profile for Kiro, so Kiro starts without any extra steps. Download the .deb from the downloads page and install it:

sudo apt install ./<file>.deb

If you installed the .deb before version 1.4.0, update Kiro or install the new .deb the same way.

If you were running Kiro from the .tar.gz archive, start Kiro from your applications menu or with kiro after installing, and delete the folder you extracted.

If you need to keep using the .tar.gz archive, move Kiro to a folder only root can change, then add an AppArmor profile for that path. Replace ~/path/to/kiro with the folder you extracted:

sudo mv ~/path/to/kiro /opt/kiro
sudo chown -R root:root /opt/kiro
sudo chmod 4755 /opt/kiro/chrome-sandbox
sudo tee /etc/apparmor.d/kiro >/dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile kiro /opt/kiro/kiro flags=(unconfined) {
  userns,
  include if exists <local/kiro>
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/kiro

Then start Kiro with /opt/kiro/bin/kiro. The profile only applies to /opt/kiro/kiro, and because that folder is owned by root, no other program can use it. Don't point a profile at a folder in your home directory: anything you can write to that path would get the same permission.

Avoid disabling the restriction with sysctl kernel.apparmor_restrict_unprivileged_userns=0. That turns the protection off for every program on the machine, not just Kiro.

Some other systems also restrict user namespaces, for example hardened kernels, or Debian with kernel.unprivileged_userns_clone=0. If Kiro shows the same chrome-sandbox error there, install the .deb package if your system supports it: its chrome-sandbox is already owned by root with mode 4755. Otherwise, move Kiro to a folder only root can change and make chrome-sandbox owned by root with mode 4755. Replace ~/path/to/kiro with the folder you extracted:

sudo mv ~/path/to/kiro /opt/kiro
sudo chown -R root:root /opt/kiro
sudo chmod 4755 /opt/kiro/chrome-sandbox

Then start Kiro with /opt/kiro/bin/kiro. Skip the AppArmor profile from the previous section: these systems don't use AppArmor for this restriction, and some don't have /etc/apparmor.d at all.

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

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

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

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)