문제 해결¶

이 가이드는 셸 통합 및 MCP 서버 연결 문제를 포함하여 Kiro의 일반적인 문제를 해결하는 데 도움이 됩니다.

Kiro 설치 문제¶

macOS: Kiro가 손상되어 열 수 없음¶

macOS에서 Kiro를 열려고 할 때 다음 오류가 발생할 수 있습니다:

Kiro is damaged and can't be opened. You should move it to the Trash.

이 팝업은 macOS 보안 기능의 오탐지로 인해 발생합니다.

이 오류를 해결하려면:

시스템 설정 → 개인 정보 보호 및 보안으로 이동하여 Kiro에 대해 허용 또는 열기를 클릭합니다.
Kiro.app을 데스크탑으로 드래그한 다음 데스크탑에서 응용 프로그램 폴더로 드래그합니다.
컴퓨터를 다시 시작합니다.
터미널을 열고 다음을 실행합니다:

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

인증 문제¶

인증 중 브라우저 리다이렉트 실패¶

Kiro로 인증할 때 브라우저로 리다이렉트되지 않는 경우 다음 플랫폼별 솔루션을 시도해 보세요:

Windows¶

로깅을 활성화한 상태로 Kiro를 실행하여 잠재적인 문제를 식별합니다:

관리자로 명령 프롬프트를 엽니다
다음 명령을 실행합니다 (실제 Kiro 설치 경로로 교체):

C:\path\to\app.exe --enable-logging
로그에서 오류를 확인합니다
액세스 거부 오류가 표시되면 사용자에게 앱을 실행할 관리자 권한이 있는지 확인합니다

macOS¶

개발자 도구를 사용하여 문제를 진단합니다:

Kiro를 엽니다
도움말 → 개발자 도구 토글로 이동합니다
콘솔 탭으로 이동합니다
로그인 프로세스 중에 보고된 오류를 관찰합니다
오류가 누락된 종속성을 나타내는 경우 PATH에서 사용 가능한지 확인합니다
- 한 가지 일반적인 문제는 누락된 ioreg 명령입니다
- ioreg가 PATH 변수에 포함되어 있는지 확인합니다:
  
  bash
  
  echo $PATH which ioreg
- ioreg가 누락된 경우 일반적으로 /usr/sbin/ioreg에 있습니다

AWS IAM Identity Center 문제¶

Q Developer Pro 구독 필요¶

Identity Center로 인증을 시도할 때 There was an error signing you in 오류가 표시되면 유효한 Q Developer Pro 구독이 있는지 확인하세요. Kiro에서 Identity Center 인증을 사용하려면 활성 Pro 구독이 필요합니다. 다음은 구독 상태를 확인하고 Pro로 업그레이드하는 방법에 대한 가이드입니다.

Q Developer 프로필의 지역 제한¶

유효한 자격 증명이 있음에도 불구하고 Identity Center로 로그인할 수 없는 경우 지역 제한 때문일 수 있습니다. Kiro는 Identity Center 인증을 위해 기본적으로 US East (N. Virginia) 지역을 사용합니다. 다른 지역에 Q Developer 프로필이 있는 경우 Identity Center로 로그인할 수 없습니다.

대안으로 Builder ID 또는 Google이나 GitHub과 같은 소셜 제공업체와 같은 다른 로그인 방법을 사용하세요. 향후 릴리스에서 이 지역 제한을 해결하기 위해 노력하고 있습니다.

세션 지속 시간 및 타임아웃¶

Identity Center 세션의 기본 타임아웃은 8시간이므로 정기적으로 다시 인증해야 합니다. 세션 지속 시간을 연장하려면 관리자가 더 긴 세션 타임아웃을 구성할 수 있습니다. 자세한 구성 지침은 사용자 세션 지속 시간 구성에 대한 AWS 문서를 참조하세요.

셸 통합 문제¶

셸 통합은 Kiro를 터미널에 연결하여 자동 명령 실행 및 결과 처리를 가능하게 합니다. 이것이 없으면 터미널 출력을 수동으로 복사하여 붙여넣어야 합니다.

빠른 수정: "shell integration unavailable"¶

Kiro 업데이트: 명령 팔레트 (Cmd + Shift + P / Ctrl + Shift + P) → Kiro: Check for Updates
통합 활성화: 명령 팔레트 (Cmd + Shift + P / Ctrl + Shift + P) → Kiro: Enable Shell Integration
재시작: Kiro를 종료하고 다시 엽니다

수동 설치¶

자동 설정이 실패하면 셸 구성에 추가합니다:

Zsh (~/.zshrc):

bash

[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path zsh)"

Bash (~/.bashrc):

bash

[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path bash)"

Fish (~/.config/fish/config.fish):

bash

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

PowerShell ($Profile):

powershell

if ($env:TERM_PROGRAM -eq "kiro") { . "$(kiro --locate-shell-integration-path pwsh)" }

터미널 명령에서 Kiro가 'Working...' 상태에 멈춰 있거나 터미널 출력을 보지 못함¶

Kiro가 터미널 출력을 읽을 수 없거나, Working... 상태에 멈춰 있거나, 이상한 문자와 형식 문제가 표시되는 경우 이는 일반적으로 터미널 통합을 방해하는 셸 사용자 정의로 인해 발생합니다. 일반적인 원인으로는 bash의 bash-it 또는 zsh의 Oh My Posh와 같은 사용자 정의와 Powerlevel10k/9k와 같은 테마가 있습니다.

Powerlevel10k 테마 사용자¶

Powerlevel10k 테마를 사용하는 경우 .p10k.zsh 파일에 다음 줄을 추가합니다:

bash

typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

또는 Kiro에서 실행할 때 이러한 사용자 정의를 비활성화할 수도 있습니다.

zsh (~/.zshrc):

bash

if [[ "$TERM_PROGRAM" == "kiro" ]]; then # 비워둠 else # 테마 또는 사용자 정의 ZSH_THEME="powerlevel10k/powerlevel10k" fi

Fish 셸 사용자¶

Fish 셸을 사용하고 터미널 출력 문제가 발생하는 경우 기존 셸 통합 스크립트에 Kiro를 수동으로 추가해야 할 수 있습니다. Fish 셸 통합 파일의 위치는 다음과 같습니다:

/Applications/Kiro.app/Contents/Resources/app/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration.fish

기본적으로 통합 스크립트는 "vscode"만 확인합니다:

bash

status is-interactive and string match --quiet "$TERM_PROGRAM" "vscode" and ! set --query VSCODE_SHELL_INTEGRATION or exit

"kiro"도 포함하도록 업데이트해야 합니다:

bash

status is-interactive and string match --quiet "$TERM_PROGRAM" "vscode" "kiro" and ! set --query VSCODE_SHELL_INTEGRATION or exit

Windows 문제¶

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

Windows에서 다음 오류가 발생하는 경우:

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.

관리자 권한으로 실행을 제거하려면:

Kiro 아이콘을 마우스 오른쪽 버튼으로 클릭합니다
더 많은 옵션 표시를 선택합니다
속성을 선택합니다
호환성 탭으로 이동합니다
관리자 권한으로 이 프로그램 실행 확인란을 선택 취소합니다
적용을 선택한 다음 확인을 선택하여 변경 사항을 저장합니다

이 단계를 완료한 후 Kiro가 정상적으로 업데이트될 수 있어야 합니다.

스크립트를 실행할 수 없음¶

PowerShell 7+에서 실행 정책을 설정합니다:

현재 정책 확인:

powershell

Get-ExecutionPolicy

실행 정책 설정:

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

OneDrive 경로 문제¶

Windows에서 OneDrive를 사용하는 경우 데스크탑 경로가 문제를 일으킬 수 있습니다:

관리자로 명령 프롬프트를 시작합니다
심볼릭 링크를 생성합니다:

mklink /J "C:\Users\<username>\Desktop" "C:\Users\<username>\OneDrive\Desktop"
IDE를 다시 시작합니다

MCP 서버 연결 문제¶

일반적인 MCP 연결 문제¶

MCP 서버에 연결하는 데 문제가 있는 경우:

서버 상태 확인:
- Kiro 패널을 열고 MCP 서버 탭으로 이동합니다
- 서버의 연결 상태 표시기를 확인합니다
- 구성 확인:
- MCP 구성 파일의 구문이 올바른지 확인합니다
- 서버 명령과 인수가 올바른지 확인합니다
- 전제 조건 확인:
- 필요한 모든 종속성이 설치되어 있는지 확인합니다
- AWS Documentation 서버의 경우 Python 3.10+ 및 uv가 설치되어 있는지 확인합니다
- 로그 검토:
- Kiro에서 출력 패널을 엽니다
- 드롭다운에서 "Kiro - MCP Logs"를 선택합니다
- 특정 오류 메시지를 찾습니다

특정 MCP 문제 수정¶

AWS 문서 서버¶

연결 실패:

bash

# uv 설치 확인 uv --version # Python 버전 확인 python --version # 서버 직접 테스트 uvx awslabs.aws-documentation-mcp-server@latest --help
검색 또는 읽기 실패:
- 인터넷 연결을 확인합니다
- 문서 페이지의 URL 형식을 확인합니다
- 더 간단한 검색 쿼리로 시도합니다

GitHub MCP 서버¶

인증 오류:
- 개인 액세스 토큰이 유효한지 확인합니다
- 토큰에 필요한 범위(repo, user)가 있는지 확인합니다
- 필요한 경우 새 토큰을 생성합니다
- 속도 제한 문제:
- GitHub API에는 사용 제한이 있습니다
- MCP 로그에서 속도 제한 상태를 확인합니다
- 더 높은 속도 제한을 가진 토큰 사용을 고려합니다

도움 받기¶

위의 문제 해결 단계를 시도했지만 여전히 도움이 필요한 경우:

일반적인 질문은 FAQ를 확인하세요
도움을 받으려면 커뮤니티 Discord에 참여하세요
다음을 포함하여 GitHub에 이슈를 제출하세요:
- 운영 체제 세부 정보
- Kiro 버전
- 이미 시도한 단계
- 오류 메시지 (있는 경우)