Troubleshooting

Kiro 사용 중 자주 마주치는 설치, 인증, 셸 통합, MCP 서버 연결 문제를 빠르게 해결하기 위한 점검 가이드입니다.

설치 관련 문제

macOS: "Kiro is damaged and can't be opened"

이 메시지는 macOS의 보안 검사에서 발생하는 false positive인 경우가 대부분입니다. 다음 순서대로 시도해 보세요.

1. System Settings → Privacy & Security에서 Allow 또는 Open anyway 클릭.
2. Kiro.app을 Desktop으로 옮긴 뒤 다시 Applications 폴더로 이동.
3. Mac을 재시작.
4. 그래도 열리지 않으면 터미널에서 quarantine 속성을 제거합니다.

   sudo xattr -d com.apple.quarantine /Applications/Kiro.app

네트워크 연결 문제

일부 사용자만 접속이 안 된다면, 사내 방화벽이나 프록시의 TLS 인스펙션이 Kiro 엔드포인트를 차단하는 경우가 흔합니다.

대표적인 증상:

• 로그인 후 "No profiles available"이 표시됨
• 로그에 Failed to retrieve profiles {"error":""}가 남음
• 로그인은 되지만 채팅과 코드 어시스트가 동작하지 않음

다음 명령으로 연결을 점검할 수 있습니다.

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

인증(Sign-in) 문제

브라우저 리다이렉트 단계에서 로그인이 끊긴다면 OS별로 로그를 확인합니다.

1. Windows: Command Prompt를 관리자 권한으로 열고 C:\path\to\app.exe --enable-logging으로 실행한 뒤 로그를 확인합니다.
2. macOS: Kiro 실행 후 Help → Toggle Developer Tools → Console 탭에서 sign-in 관련 오류를 확인합니다.
3. 의존 명령(ioreg 등, 보통 /usr/sbin/ioreg)이 PATH에 있는지 점검합니다.

   echo $PATH
   which ioreg

AWS IAM Identity Center 사용 시에는 활성 구독이 필요하며, 프로파일은 현재 US East (N. Virginia)와 Europe (Frankfurt) 리전에서만 지원됩니다. 기본 세션 만료 시간은 8시간이며, 관리자 설정으로 연장할 수 있습니다.

Shell 통합 문제

"shell integration unavailable" 메시지가 보이면 우선 다음을 시도하세요.

1. Command Palette(Cmd + Shift + P / Ctrl + Shift + P)에서 Kiro: Check for Updates 실행.
2. Command Palette에서 Kiro: Enable Shell Integration 실행.
3. Kiro를 완전히 종료한 뒤 다시 시작.

자동 활성화가 안 되면 셸별 설정 파일에 직접 추가합니다.

• 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)" }

"Working..."에서 멈추거나 터미널 출력이 없는 경우

bash-it, Oh My Posh, Powerlevel10k/9k 같은 커스텀 프롬프트가 통합 시퀀스를 가로막는 경우가 많습니다.

Powerlevel10k 사용 시 .p10k.zsh에 다음 한 줄을 추가합니다.

typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

또는 Kiro 터미널에서만 테마를 끄도록 분기합니다.

if [[ "$TERM_PROGRAM" == "kiro" ]]; then
  # Leave empty
else
  ZSH_THEME="powerlevel10k/powerlevel10k"
fi

Windows 환경 이슈

관리자 권한 설치로 인해 업데이트가 비활성화됨

Kiro는 시스템 전역 설치를 지원하지 않습니다. 사용자 스코프 설치를 관리자 권한으로 실행하면 자동 업데이트가 막힙니다.

1. Kiro 아이콘을 우클릭 → Show more options → Properties.
2. Compatibility 탭에서 Run this program as an administrator 체크 해제.
3. Apply → OK.

PowerShell 스크립트 실행 정책

Get-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

OneDrive로 인한 Desktop 경로 충돌

Desktop이 OneDrive 하위로 옮겨져 경로가 깨질 때는 심볼릭 링크로 보정합니다.

mklink /J "C:\Users\<username>\Desktop" "C:\Users\<username>\OneDrive\Desktop"

MCP 서버 연결 문제

Kiro 패널의 MCP servers 탭에서 연결 상태 인디케이터를 먼저 확인하세요. 문제 해결의 기본 순서는 다음과 같습니다.

1. 설정 파일의 command, 인자(arguments), JSON 문법을 점검.
2. 의존 런타임 확인. 예: AWS Documentation 서버는 Python 3.10+ 와 uv 필요.
3. Output 패널에서 "Kiro - MCP Logs" 드롭다운을 선택해 로그 확인.

AWS Documentation 서버 점검:

uv --version
python --version
uvx awslabs.aws-documentation-mcp-server@latest --help

GitHub MCP 서버는 personal access token에 repo, user scope이 포함돼 있는지 확인하고, rate limit에 자주 걸린다면 한도가 더 높은 토큰으로 교체하는 것을 검토하세요.