문제 해결¶
증상별 빠른 점검¶
| 증상 | 가능한 원인 | 조치 |
|---|---|---|
semantic/hybrid 오류 또는 결과 품질 저하 |
인덱스/임베딩 준비 부족 | cgrep index 재실행 후 임베딩 설정 확인 |
| 하위 디렉터리에서 결과가 누락됨 | 검색 범위 불일치 | -p <path>로 범위 명시 |
| 에이전트 출력이 너무 큼 | 예산 설정이 느슨함 | --budget tight 또는 --profile agent 사용 |
| semantic/hybrid가 거의 비어 보임 | 임베딩/인덱스 미준비 | cgrep index --embeddings auto로 재생성 |
| keyword는 되는데 semantic/hybrid는 실패 | 모드별 요구 조건 차이 | keyword는 scan 폴백 가능, semantic/hybrid는 인덱스 필수 |
Error: Search query cannot be empty |
쿼리가 비어 있거나 공백만 있음 (--regex "" 포함) |
비어 있지 않은 쿼리 전달 |
read에서 Error: Path cannot be empty |
경로 인자가 비어 있음 | cgrep read <path> 형태로 유효 경로 전달 |
-로 시작하는 쿼리 검색 시 error: unexpected argument '<path>' found |
-- 구분자를 옵션/경로보다 먼저 둠 |
옵션/경로를 먼저 두고 마지막에 -- 사용 |
mcp install에서 invalid value 'codex' for '<HOST>' |
codex는 이 명령의 host 값이 아님 |
Codex는 cgrep agent install codex 사용 |
CLI search에서 invalid search mode 'auto' 또는 invalid value 'auto' for '--mode <MODE>' |
auto/default는 MCP 호환 동작이지 CLI 엔진 모드가 아님 |
CLI는 --mode keyword|semantic|hybrid를 사용하고 retrieval 기본값은 --profile agent|human|fast로 조절 |
| MCP 호출이 timeout 되거나 scope를 더 줄이라고 나옴 | 요청 범위/출력이 아직 너무 큼 | path → glob → changed → file_type 순으로 다시 좁히고 limit / context를 줄임 |
| MCP 출력이 cap을 초과함 | 매치 수나 문맥이 너무 많음 | profile=agent를 사용하고 limit / context를 줄이거나 scope를 더 좁힘 |
| 큰 수정 뒤 MCP 결과가 stale해 보임 | 장시간 세션이 새 요청 lifecycle을 다시 시작해야 함 | scope를 줄인 뒤 MCP 세션/클라이언트를 재시작하고 다시 호출 |
Linux 설치 후 GLIBC_2.39 not found |
호스트 glibc가 다운로드 자산보다 낮음 | 최신 릴리즈 사용(현재 Linux 빌드 기준: Ubuntu 22.04 / glibc 2.35) 또는 소스 설치 |
빠른 복구 순서¶
cgrep index
cgrep search "sanity check" -m 5
cgrep search "sanity check" --mode keyword -m 5
cgrep --format json2 --compact status
CGREP_BIN=cgrep bash scripts/validate_all.sh
Search / MCP 재-scope 체크리스트¶
요청이 너무 넓거나 느리거나 결과가 너무 크면 다음 순서로 좁히세요:
-p <path>/ MCPpath--glob <pattern>/ MCPglob-u [rev]/ MCPchanged-t <lang>/ MCPfile_typelimit/context줄이기- 더 작은 payload가 필요하면 CLI는
--profile agent -B tight, MCP는profile=agent
예시:
cgrep s "retry budget" -p src/ --glob "*.rs" -u HEAD -t rust
cgrep s "retry budget" -p src/ --profile agent -B tight --format json2 --compact
Search mode vs profile¶
기억할 규칙:
mode= 엔진 선택keywordsemantichybridprofile= retrieval 기본값 / 출력 형태humanagentfast
예시:
# CLI: 엔진을 명시적으로 선택
cgrep s "auth flow" --mode keyword
# CLI: 에이전트 친화 retrieval 기본값
cgrep s "auth flow" --profile agent -B tight --format json2 --compact
# 사용처 조회의 -M auto는 search --mode와 별개
cgrep r AuthService -M auto
MCP 클라이언트에서는 mode=auto, mode=default를 기본 검색 동작에 대한 호환 alias로 허용합니다. 별도의 검색 엔진 모드는 아닙니다.