문제 해결

"Service is experiencing high traffic. Please try again later!"

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

발생하는 경우:

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

복구 단계(순서대로):

설치 및 설정 문제

시스템 요구 사항:

• 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"로 표시되어야 함)

클린 재설치 절차:

로그 확인:

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

Verdent for VS Code에 로그인할 수 없음

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

해결 방법:

무료 체험 크레딧을 받지 못함

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

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

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

등록 실패

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

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

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

모델 누락(Claude, GPT, Gemini)

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

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

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

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

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

성능 문제

증상:

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

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

이미지 관련 오류 메시지

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

file_edit 실패

오류: "Failed to find exact match"

원인:

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

해결 방법:

# 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)

bash 명령 실패

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

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

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

# 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를 사용합니다
• 파일/디렉터리 권한을 확인합니다

검색 결과가 없음

문제: grep_file 또는 glob이 예상한 파일을 찾지 못함

패턴 문법 확인:

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

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

제외 항목 확인:

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

대소문자 구분:

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

서브에이전트가 호출되지 않음

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

체크리스트:

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

수동 테스트:

@subagent-name perform task

내장 서브에이전트 동작

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

일반적인 원인:

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

해결 방법:

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

AGENTS.md가 적용되지 않음

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

진단:

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

우선순위 확인:

# 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)

MCP 연결 실패

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

진단 단계:

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

일반적인 해결 방법:

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

바이너리 파일 제한

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

우회 방법:

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

큰 파일 처리

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

우회 방법:

# 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")

크로스 플랫폼 명령 차이

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

우회 방법:

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

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

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