문제 해결 가이드 (Troubleshooting guide)

이 가이드에서는 다음 주제를 포함하여 일반적인 문제에 대한 해결 방법과 디버깅 팁을 제공합니다:

• 인증 또는 로그인 오류
• 자주 묻는 질문 (FAQ)
• 디버깅 팁
• 유사한 기존 GitHub 이슈 확인 또는 새 이슈 생성

인증 또는 로그인 오류 (Authentication or login errors)

• 오류: You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.

  • 원인: 이 오류는 Gemini CLI가 GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_PROJECT_ID 환경 변수가 정의되어 있음을 감지할 때 발생할 수 있습니다. 이러한 변수를 설정하면 조직 구독 확인이 강제됩니다. 조직 구독과 연결되지 않은 개인 Google 계정을 사용하는 경우 문제가 될 수 있습니다.

  • 해결 방법:

    • 개인 사용자: GOOGLE_CLOUD_PROJECT 및 GOOGLE_CLOUD_PROJECT_ID 환경 변수 설정을 해제합니다. 셸 구성 파일(예: .bashrc, .zshrc) 및 모든 .env 파일에서 이 변수들을 확인하고 제거하세요. 그래도 문제가 해결되지 않으면 다른 Google 계정을 사용해 보세요.

    • 조직 사용자: Google Cloud 관리자에게 문의하여 조직의 Gemini Code Assist 구독에 추가해 달라고 요청하세요.

• 오류: Failed to login. Message: Your current account is not eligible... because it is not currently available in your location.

  • 원인: Gemini CLI는 현재 사용자의 위치를 지원하지 않습니다. 지원되는 위치의 전체 목록은 다음 페이지를 참조하세요:
    • 개인용 Gemini Code Assist: 사용 가능 위치 (opens in a new tab)

• 오류: Failed to login. Message: Request contains an invalid argument

  • 원인: Google Workspace 계정 사용자나 Gmail 계정과 연결된 Google Cloud 계정 사용자는 Google Code Assist 요금제의 무료 등급을 활성화하지 못할 수 있습니다.
  • 해결 방법: Google Cloud 계정의 경우 GOOGLE_CLOUD_PROJECT를 프로젝트 ID로 설정하여 이 문제를 해결할 수 있습니다. 또는 Google AI Studio (opens in a new tab)에서 Gemini API 키를 얻을 수 있으며, 여기에도 별도의 무료 등급이 포함되어 있습니다.

• 오류: UNABLE_TO_GET_ISSUER_CERT_LOCALLY 또는 unable to get local issuer certificate

  • 원인: SSL/TLS 트래픽을 가로채고 검사하는 방화벽이 있는 회사 네트워크에 있을 수 있습니다. 이 경우 Node.js에서 신뢰할 수 있는 사용자 지정 루트 CA 인증서가 필요한 경우가 많습니다.
  • 해결 방법: 먼저 NODE_USE_SYSTEM_CA 설정을 시도하고, 문제가 해결되지 않으면 NODE_EXTRA_CA_CERTS를 설정하세요.
    • NODE_USE_SYSTEM_CA=1 환경 변수를 설정하여 Node.js가 운영 체제의 기본 인증서 저장소(회사 인증서가 일반적으로 이미 설치되어 있음)를 사용하도록 합니다.
      • 예: export NODE_USE_SYSTEM_CA=1
    • NODE_EXTRA_CA_CERTS 환경 변수를 회사 루트 CA 인증서 파일의 절대 경로로 설정합니다.
      • 예: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

일반적인 오류 메시지 및 해결 방법 (Common error messages and solutions)

• 오류: MCP 서버 시작 시 EADDRINUSE (Address already in use).

  • 원인: MCP 서버가 바인딩하려는 포트를 다른 프로세스가 이미 사용하고 있습니다.
  • 해결 방법: 포트를 사용 중인 다른 프로세스를 중지하거나 MCP 서버가 다른 포트를 사용하도록 구성하세요.

• 오류: Command not found (gemini로 Gemini CLI 실행 시도 시).

  • 원인: Gemini CLI가 올바르게 설치되지 않았거나 시스템의 PATH에 없습니다.
  • 해결 방법: 업데이트 방법은 Gemini CLI 설치 방법에 따라 다릅니다:
    • gemini를 전역으로 설치한 경우, npm 전역 바이너리 디렉터리가 PATH에 있는지 확인하세요. npm install -g @google/gemini-cli@latest 명령을 사용하여 Gemini CLI를 업데이트할 수 있습니다.
    • 소스에서 gemini를 실행하는 경우, 올바른 명령(예: node packages/cli/dist/index.js ...)을 사용하여 호출하는지 확인하세요. Gemini CLI를 업데이트하려면 리포지토리에서 최신 변경 사항을 가져온(pull) 후 npm run build 명령을 사용하여 다시 빌드하세요.

• 오류: MODULE_NOT_FOUND 또는 가져오기(import) 오류.

  • 원인: 종속성이 올바르게 설치되지 않았거나 프로젝트가 빌드되지 않았습니다.
  • 해결 방법:
    1. npm install을 실행하여 모든 종속성이 있는지 확인하세요.
    2. npm run build를 실행하여 프로젝트를 컴파일하세요.
    3. npm run start를 실행하여 빌드가 성공적으로 완료되었는지 확인하세요.

• 오류: "Operation not permitted", "Permission denied" 또는 유사한 오류.

  • 원인: 샌드박싱이 활성화된 경우, Gemini CLI는 프로젝트 디렉터리 외부 또는 시스템 임시 디렉터리에 쓰는 것과 같이 샌드박스 구성에 의해 제한된 작업을 시도할 수 있습니다.
  • 해결 방법: 샌드박스 구성을 사용자 지정하는 방법을 포함한 자세한 내용은 구성: 샌드박싱 문서를 참조하세요.

• Gemini CLI가 "CI" 환경에서 대화형 모드로 실행되지 않음

  • 문제: CI_로 시작하는 환경 변수(예: CI_TOKEN)가 설정된 경우 Gemini CLI가 대화형 모드로 진입하지 않음(프롬프트가 나타나지 않음). 이는 기본 UI 프레임워크에서 사용하는 is-in-ci 패키지가 이러한 변수를 감지하고 비대화형 CI 환경이라고 가정하기 때문입니다.
  • 원인: is-in-ci 패키지는 CI, CONTINUOUS_INTEGRATION 또는 CI_ 접두사가 있는 환경 변수의 존재를 확인합니다. 이러한 변수가 발견되면 환경이 비대화형임을 알리며, 이로 인해 Gemini CLI가 대화형 모드로 시작되지 않습니다.
  • 해결 방법: CLI 기능에 CI_ 접두사가 붙은 변수가 필요하지 않은 경우, 해당 명령에 대해 일시적으로 설정을 해제할 수 있습니다. 예: env -u CI_TOKEN gemini

• 프로젝트 .env 파일에서 DEBUG 모드가 작동하지 않음

  • 문제: 프로젝트의 .env 파일에 DEBUG=true를 설정해도 gemini-cli의 디버그 모드가 활성화되지 않습니다.
  • 원인: DEBUG 및 DEBUG_MODE 변수는 gemini-cli 동작과의 간섭을 방지하기 위해 프로젝트 .env 파일에서 자동으로 제외됩니다.
  • 해결 방법: 대신 .gemini/.env 파일을 사용하거나, settings.json에서 advanced.excludedEnvVars 설정을 구성하여 제외되는 변수를 줄이세요.

종료 코드 (Exit codes)

Gemini CLI는 종료 이유를 나타내기 위해 특정 종료 코드를 사용합니다. 이는 스크립팅 및 자동화에 특히 유용합니다.

디버깅 팁 (Debugging tips)

• CLI 디버깅:

  • 더 자세한 출력을 보려면 --debug 플래그를 사용하세요. 대화형 모드에서 F12를 눌러 디버그 콘솔을 볼 수 있습니다.
  • 사용자별 구성 또는 캐시 디렉터리에서 자주 발견되는 CLI 로그를 확인하세요.

• Core 디버깅:

  • 서버 콘솔 출력에서 오류 메시지나 스택 추적을 확인하세요.
  • 구성 가능한 경우 로그 상세 수준(verbosity)을 높이세요. 예를 들어, DEBUG_MODE 환경 변수를 true 또는 1로 설정하세요.
  • 서버 측 코드를 단계별로 실행해야 하는 경우 Node.js 디버깅 도구(예: node --inspect)를 사용하세요.

• 도구 문제:

  • 특정 도구가 실패하는 경우, 도구가 수행하는 명령이나 작업의 가장 간단한 버전을 실행하여 문제를 격리해 보세요.
  • run_shell_command의 경우, 명령이 셸에서 직접 작동하는지 먼저 확인하세요.
  • 파일 시스템 도구의 경우, 경로가 올바른지 확인하고 권한을 확인하세요.

• 사전 점검 (Pre-flight checks):

  • 코드를 커밋하기 전에 항상 npm run preflight를 실행하세요. 이렇게 하면 서식 지정, 린팅 및 유형 오류와 관련된 많은 일반적인 문제를 발견할 수 있습니다.

유사한 기존 GitHub 이슈 확인 또는 새 이슈 생성

이 문제 해결 가이드에서 다루지 않은 문제가 발생하면 Gemini CLI GitHub 이슈 트래커 (opens in a new tab)를 검색해 보세요. 유사한 이슈를 찾을 수 없는 경우, 상세한 설명과 함께 새로운 GitHub 이슈를 생성하는 것을 고려해 보세요. 풀 리퀘스트도 환영합니다!

참고: "🔒Maintainers only" 태그가 지정된 이슈는 프로젝트 관리자를 위해 예약되어 있습니다. 이러한 이슈와 관련된 풀 리퀘스트는 수락하지 않습니다.