# 문제 해결 (/ko/docs/verdent-for-vscode/help-support/common-issues)

> 일반적인 문제, 진단, 해결 방법



### 배울 내용 [#배울-내용]

Verdent for VS Code에서 자주 쓰는 문제 해결 절차, 진단 단계, 알려진 문제의 우회 방법을 알아봅니다.

<Info>
  사용자가 많이 보고한 주요 문제에 대한 자세한 문제 해결 내용은 지원 데이터를 바탕으로 정리 중입니다. 이 페이지는 일반적인 진단 절차를 제공합니다. 여기에 포함되지 않은 특정 문제는 [support@verdent.ai](mailto:support@verdent.ai)로 문의하세요.
</Info>

***

## 빠른 진단 [#빠른-진단]

<Tabs>
  <Tab title="서비스 오류(가장 흔함)">
    ### "Service is experiencing high traffic. Please try again later!" [#service-is-experiencing-high-traffic-please-try-again-later]

    **사용자가 가장 자주 만나는 오류 1위입니다.** Verdent 서비스가 일시적으로 과부하 상태임을 의미합니다.

    **발생하는 경우:**

    * 사용량이 많은 피크 시간대
    * 백엔드 서비스에 부하가 큰 경우
    * 일시적인 서비스 품질 저하

    **복구 단계(순서대로):**

    <Steps>
      <Step title="메시지 롤백" stepNumber="1">
        오류가 계속되면 가장 최근 메시지를 롤백합니다.

        * 채팅 인터페이스에서 롤백/실행 취소 버튼을 선택합니다
        * 잠시 기다린 뒤 요청을 다시 제출합니다
      </Step>

      <Step title="새 세션 시작" stepNumber="2">
        오류가 계속되면 새 세션을 시작합니다.

        * 상단 바에서 "+"(새 세션) 버튼을 선택합니다
        * 이렇게 하면 컨텍스트와 도구 승인이 초기화됩니다
        * 깨끗한 세션에서 요청을 다시 제출합니다
      </Step>

      <Step title="기다렸다가 다시 시도" stepNumber="3">
        30\~60초 기다린 뒤 요청을 다시 시도합니다. 대부분의 서비스 문제는 빠르게 해결됩니다.
      </Step>
    </Steps>

    <Warning>
      여러 세션에서 문제가 5\~10분 이상 계속되면 [Verdent 상태 페이지](https://verdent.ai/status)를 확인하거나 [support@verdent.ai](mailto:support@verdent.ai)로 문의하세요.
    </Warning>
  </Tab>

  <Tab title="설치 및 설정">
    ### 설치 및 설정 문제 [#설치-및-설정-문제]

    **시스템 요구 사항:**

    * **VS Code 버전:** 1.90.0 이상(필수)
    * **인터넷 연결:** 활성 연결 필요
    * **구독:** 활성 Verdent 구독

    **기본 진단 체크리스트:**

    1. **VS Code 버전 확인:** Help → About(1.90.0 이상이어야 함)
    2. **인터넷 연결 확인:** Verdent에는 활성 연결이 필요합니다
    3. **구독 확인:** Verdent 구독이 활성 상태인지 확인합니다
    4. **VS Code 재시작:** 설치 또는 구성 변경 후 재시작합니다
    5. **확장 프로그램 상태 확인:** View → Extensions → Verdent("Enabled"로 표시되어야 함)

    **클린 재설치 절차:**

    <Steps>
      <Step title="Verdent 제거">
        View → Extensions → Verdent → Uninstall
      </Step>

      <Step title="VS Code 재시작">
        VS Code를 완전히 닫은 뒤 다시 엽니다
      </Step>

      <Step title="Verdent 재설치">
        View → Extensions → Search "Verdent" → Install
      </Step>
    </Steps>

    **로그 확인:**

    * Output 패널을 엽니다: View → Output
    * 드롭다운에서 "Verdent"을 선택합니다
    * 오류 메시지나 스택 트레이스를 찾습니다

    <Info>
      대부분의 설치 문제는 간단한 VS Code reload 또는 클린 재설치로 해결됩니다. 문제가 계속되면 로그를 확인하고 로그 세부 정보와 함께 지원팀에 문의하세요.
    </Info>
  </Tab>

  <Tab title="인증 및 계정">
    ### Verdent for VS Code에 로그인할 수 없음 [#verdent-for-vs-code에-로그인할-수-없음]

    **가장 흔한 원인:** 프록시 구성 문제

    **해결 방법:**

    <Steps>
      <Step title="VS Code 설정 열기">
        `Cmd+,`(macOS) 또는 `Ctrl+,`(Windows/Linux)를 누릅니다
      </Step>

      <Step title="프록시 설정 검색">
        설정 검색 바에서 "useProxy" 또는 "verdent.enableProxy"를 검색합니다
      </Step>

      <Step title="프록시 상태 전환">
        프록시 설정을 현재 상태와 반대로 켜거나 끕니다
      </Step>

      <Step title="로그인 다시 시도">
        Verdent에 다시 로그인해 봅니다
      </Step>
    </Steps>

    <Info>
      회사 방화벽 뒤에 있다면 프록시 설정을 켜야 할 수 있습니다. 홈 네트워크를 사용 중이라면 꺼 보세요.
    </Info>

    ***

    ### 무료 체험 크레딧을 받지 못함 [#무료-체험-크레딧을-받지-못함]

    **오류:** 무료 체험 크레딧을 받지 못했거나 무료 체험 접근이 거부됨

    **이유:** 가입 중 서비스 약관 위반이 감지됨

    **해결:** 무료 체험 접근 관련 도움을 받으려면 [support@verdent.ai](mailto:support@verdent.ai)로 문의하세요. 지원팀이 계정을 검토하고 문제 해결을 도와드립니다.

    ***

    ### 등록 실패 [#등록-실패]

    **오류:** 계정 등록이 거부되었거나 제한됨

    **이유:** 등록이 Verdent의 서비스 약관을 위반하여 접근 제한이 적용됨

    **해결:** 도움을 받으려면 [support@verdent.ai](mailto:support@verdent.ai)로 문의하세요. 지원팀이 등록 내용을 검토하고 문제 해결 방법을 안내할 수 있습니다.

    ***

    ### 모델 누락(Claude, GPT, Gemini) [#모델-누락claude-gpt-gemini]

    **문제:** 모델 선택에서 Claude, GPT 또는 Gemini 모델을 찾을 수 없음

    **이유:** 모델 제공업체의 위치 기반 제한

    **설명:** 일부 AI 모델 제공업체는 지역 제한을 두고 있어 특정 지리적 위치에서는 일부 모델을 사용할 수 없습니다. 이런 경우:

    * 제한된 모델은 모델 선택 메뉴에 표시되지 않습니다
    * 사용 가능한 다른 모든 모델은 중단 없이 계속 사용할 수 있습니다
    * 구독이나 크레딧에는 영향이 없습니다

    **사용 가능한 모델 확인:** [https://www.verdent.ai/regions](https://www.verdent.ai/regions) 에서 해당 지역에서 사용할 수 있는 모델을 확인하세요

    <Note>
      지역 제한은 Verdent가 아니라 AI 모델 제공업체(Anthropic, OpenAI, Google)가 설정합니다. Verdent는 이러한 제한을 우회할 수 없습니다.
    </Note>
  </Tab>

  <Tab title="성능">
    ### 성능 문제 [#성능-문제]

    **증상:**

    * 느린 응답 시간
    * 컨텍스트 창 가득 참 오류
    * 도구 실행 시간 초과

    **일반적인 원인 및 해결 방법:**

    | 문제         | 원인              | 해결 방법                                                             |
    | ---------- | --------------- | ----------------------------------------------------------------- |
    | 느린 응답      | 큰 파일을 읽고 있음     | 줄 범위를 사용합니다: `file_read("file.js", start_line=100, max_lines=50)` |
    | 컨텍스트 가득 참  | 긴 대화 기록         | 서브에이전트에 위임하거나 새 대화를 시작합니다                                         |
    | 도구 시간 초과   | 오래 실행되는 bash 명령 | 명시적 타임아웃을 설정하거나 더 작은 명령으로 나눕니다                                    |
    | 높은 메모리 사용량 | 병렬 작업이 너무 많음    | 동시 도구 실행 수를 제한합니다                                                 |

    <Tip>
      탐색 작업은 @Explorer 서브에이전트에 위임하여 메인 컨텍스트를 보존하세요.
    </Tip>
  </Tab>

  <Tab title="이미지 오류">
    ### 이미지 관련 오류 메시지 [#이미지-관련-오류-메시지]

    **일반적인 이미지 처리 오류 빠른 참조:**

    | 오류 메시지             | 원인                                             | 해결 방법                             |
    | ------------------ | ---------------------------------------------- | --------------------------------- |
    | **지원되지 않는 이미지 유형** | JPEG, PNG, GIF 또는 WebP 이미지만 지원됩니다              | 롤백한 뒤 이미지 유형을 지원되는 형식으로 변경합니다     |
    | **이미지 크기가 너무 큼**   | 이미지 너비 또는 높이는 8000픽셀을 초과할 수 없습니다               | 롤백한 뒤 이미지 크기를 8000×8000 이하로 조정합니다 |
    | **입력이 너무 김**       | 입력이 모델에서 허용하는 최대 길이를 초과했습니다                    | 입력을 단순화하거나 이미지 크기를 줄입니다           |
    | **파일이 너무 큼**       | 이미지 크기는 5MB를 초과할 수 없습니다                        | 롤백한 뒤 압축된 이미지(최대 5MB)를 보냅니다       |
    | **읽을 수 없는 이미지**    | 이미지를 처리할 수 없습니다. 파일이 손상되었거나 지원되지 않는 형식일 수 있습니다 | 롤백한 뒤 이미지를 유효한 파일로 교체합니다          |
  </Tab>
</Tabs>

***

## 도구별 문제 [#도구별-문제]

<Tabs>
  <Tab title="file_edit 실패">
    ### file\_edit 실패 [#file_edit-실패]

    **오류:** "Failed to find exact match"

    **원인:**

    * 마지막 file\_read 이후 텍스트가 변경됨
    * 공백 차이(탭과 스페이스)
    * 파일에서 문자열이 고유하지 않음

    **해결 방법:**

    ```bash
    # 1. Read file again to get current state
    file_read("file.js")

    # 2. Use larger context string for uniqueness
    file_edit("file.js",
      old_string="function foo() {\n  return 42;\n}",
      new_string="...")

    # 3. For multiple identical strings, use replace_all
    file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
    ```

    <Warning>
      현재 상태를 확인할 수 있도록 편집 직전에 항상 파일을 읽으세요.
    </Warning>
  </Tab>

  <Tab title="bash 실패">
    ### bash 명령 실패 [#bash-명령-실패]

    **오류:** 명령 시간 초과 또는 실행 실패

    **최대 타임아웃:** 120초(2분, 하드 리밋)

    **해결 방법:** 긴 명령을 더 작은 작업으로 나눕니다.

    ```bash
    # Instead of one long command, break into steps
    bash("step1")  # Completes in < 2min
    bash("step2")  # Completes in < 2min
    ```

    **명령을 찾을 수 없음:**

    * 명령이 있는지 확인합니다: `bash("which command-name")`
    * 올바른 경로인지 확인하거나 먼저 환경을 활성화합니다
    * 실행 파일에는 전체 경로를 사용합니다

    **권한 오류:**

    * 명령은 사용자 권한으로 실행됩니다
    * 필요한 경우에만 Manual Accept Mode에서 `sudo`를 사용합니다
    * 파일/디렉터리 권한을 확인합니다
  </Tab>

  <Tab title="검색 문제">
    ### 검색 결과가 없음 [#검색-결과가-없음]

    **문제:** grep\_file 또는 glob이 예상한 파일을 찾지 못함

    **패턴 문법 확인:**

    ```bash
    # Wrong
    grep_file("*.ts")  # Missing ** for recursive

    # Correct
    grep_file("**/*.ts")  # Recursive search
    ```

    **제외 항목 확인:**

    ```bash
    # Ensure not accidentally excluding target files
    glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
    ```

    **대소문자 구분:**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

***

## 서브에이전트 및 구성 문제 [#서브에이전트-및-구성-문제]

<Tabs>
  <Tab title="서브에이전트가 호출되지 않음">
    ### 서브에이전트가 호출되지 않음 [#서브에이전트가-호출되지-않음]

    **문제:** 사용자 지정 서브에이전트가 자동으로 활성화되지 않음

    **체크리스트:**

    * 파일 위치: `~/.verdent/subagents/[name].md`
    * `name` 및 `description`가 포함된 유효한 YAML frontmatter
    * 호출 정책이 사용 방식과 일치함(strict는 @-mention 필요)
    * "When to use" 가이드라인이 요청 패턴과 일치함
    * markdown 파일에 문법 오류가 없음

    **수동 테스트:**

    ```
    @subagent-name perform task
    ```

    <Tip>
      자동 호출 문제를 해결하기 전에 명시적인 @-mention을 사용해 서브에이전트가 작동하는지 확인하세요.
    </Tip>
  </Tab>

  <Tab title="내장 서브에이전트">
    ### 내장 서브에이전트 동작 [#내장-서브에이전트-동작]

    **문제:** @Explorer, @Verifier 또는 @Code-reviewer가 예상대로 동작하지 않음

    **일반적인 원인:**

    * 요청이 서브에이전트의 전문 영역과 맞지 않음
    * 서브에이전트 컨텍스트가 가득 참(드묾)
    * 메인 대화 컨텍스트가 라우팅에 영향을 줌

    **해결 방법:**

    * 명시적인 @-mention으로 특정 서브에이전트를 강제합니다
    * 서브에이전트 전문성과 맞도록 요청을 다시 표현합니다
    * 컨텍스트가 문제라면 새 대화를 시작합니다
  </Tab>

  <Tab title="AGENTS.md 규칙">
    ### AGENTS.md가 적용되지 않음 [#agentsmd가-적용되지-않음]

    **문제:** 프로젝트 규칙이 Verdent 동작에 영향을 주지 않음

    **진단:**

    1. **위치:** 파일은 프로젝트 루트 디렉터리에 있어야 합니다
    2. **문법:** 유효한 Markdown이어야 합니다(문법 오류 확인)
    3. **구체성:** 규칙은 지시형이어야 합니다. "Try to use X"가 아니라 "Always use X"처럼 작성합니다
    4. **테스트:** 새 대화를 시작해 새로 적용되는지 테스트합니다

    **우선순위 확인:**

    ```markdown
    # In AGENTS.md (highest priority)
    - Use 4-space indentation

    # In VERDENT.md (lower priority)
    - Use 2-space indentation

    # Result: 4-space indentation (AGENTS.md wins)
    ```
  </Tab>

  <Tab title="MCP 연결">
    ### MCP 연결 실패 [#mcp-연결-실패]

    **오류:** MCP 서버에 연결할 수 없음

    **진단 단계:**

    1. **mcp.json 확인:** `~/.verdent/mcp.json`의 JSON 문법이 유효한지 확인합니다
    2. **서버 실행 중:** MCP 서버 프로세스가 활성 상태인지 확인합니다
    3. **네트워크:** 서버 엔드포인트와의 연결을 확인합니다
    4. **인증:** 자격 증명이 올바른지 확인합니다
    5. **로그:** 오류 세부 정보를 확인하려면 MCP 서버 로그를 확인합니다

    **일반적인 해결 방법:**

    * MCP 서버를 재시작합니다
    * 연결 문자열 형식을 확인합니다
    * MCP 트래픽을 허용하는 방화벽 규칙을 확인합니다
    * API 키 또는 토큰을 검증합니다
  </Tab>
</Tabs>

***

## 알려진 문제 및 우회 방법 [#알려진-문제-및-우회-방법]

<Tabs>
  <Tab title="바이너리 파일">
    ### 바이너리 파일 제한 [#바이너리-파일-제한]

    **문제:** 이미지, PDF, 컴파일된 바이너리를 편집할 수 없음

    **우회 방법:**

    ```bash
    # Use bash to call external tools
    bash("convert input.png -resize 50% output.png")
    bash("pdftotext document.pdf output.txt")
    ```

    <Info>
      바이너리 파일 수정에는 bash 명령으로 호출하는 외부 도구가 필요합니다.
    </Info>
  </Tab>

  <Tab title="큰 파일">
    ### 큰 파일 처리 [#큰-파일-처리]

    **문제:** 10,000줄이 넘는 파일은 컨텍스트 문제를 일으킴

    **우회 방법:**

    ```bash
    # Always use line ranges for large files
    file_read("large.log", start_line=1000, max_lines=100)

    # Search first to find relevant sections
    grep_content("ERROR", glob="large.log")
    ```

    <Tip>
      먼저 grep\_content로 검색해 관련 줄 번호를 찾은 다음, 해당 특정 범위만 읽으세요.
    </Tip>
  </Tab>

  <Tab title="플랫폼 차이">
    ### 크로스 플랫폼 명령 차이 [#크로스-플랫폼-명령-차이]

    **문제:** bash 명령이 Windows와 Unix에서 다름

    **우회 방법:**

    ```bash
    # Use cross-platform tools when possible
    bash("npm run build")  # Works everywhere

    # Or conditional execution
    bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
    ```

    **모범 사례:** 크로스 플랫폼 호환성을 위해 npm scripts를 사용하세요.
  </Tab>
</Tabs>

***

## 추가 도움 받기 [#추가-도움-받기]

### 지원 채널 [#지원-채널]

**여기에 포함되지 않은 특정 문제:**

* **이메일:** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord:** 실시간 지원을 받으려면 Verdent 커뮤니티에 [참여하세요](https://discord.com/invite/NGjXEZcbJq)
* **GitHub 이슈:** 버그를 보고하거나 기능을 요청하세요

**문제를 보고할 때 포함할 내용:**

1. Verdent 버전(Extensions 패널에서 확인)
2. VS Code 버전
3. 운영 체제
4. 오류 메시지(정확한 텍스트)
5. 재현 단계
6. 기대 동작과 실제 동작

***

### 진단 정보 수집 [#진단-정보-수집]

**지원팀의 진단을 돕기 위해:**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

***

## 함께 보기 [#함께-보기]

<CardGroup cols="2">
  <Card title="FAQ" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    자주 묻는 질문
  </Card>

  <Card title="제한 사항" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    알려진 제한 사항과 제약
  </Card>
</CardGroup>