Ropeman 사용 중 문제가 생겼다면 아래 케이스부터 확인해 보세요. 여기서 해결되지 않는 문제는 [email protected]로 제보해 주시기 바랍니다.

파싱 관련

일부 파일이 파싱되지 않고 건너뛰어집니다

• 증상 — 분석 후 다이어그램에 특정 파일이 포함되지 않습니다.
• 원인 — 파일 크기가 500 KB를 초과하거나, 지원 언어가 아니거나, 파서가 문법 오류를 만났을 수 있습니다.
• 해결 — 500 KB 이상 파일은 의도적으로 스킵됩니다. 지원 언어 목록은 자주 묻는 질문을 참고하세요. 브라우저 개발자 도구 콘솔에서 파서 경고 메시지를 확인하면 어떤 파일이 스킵됐는지 알 수 있습니다.

“파일이 너무 많습니다” 에러

• 증상 — 폴더를 드롭하면 “프로젝트가 너무 큽니다”라는 메시지가 뜹니다.
• 원인 — Ropeman은 성능 보호를 위해 최대 2,000개 파일 만 처리합니다.
• 자동 제외 — node_modules, .git, dist, build, __pycache__, 가상 환경 폴더처럼 흔한 의존성·산출물·캐시 디렉토리는 폴더를 여는 시점에 자동으로 건너뜁니다. 직접 정리하실 필요가 없습니다.
• 해결 — 자동 제외 후에도 한도를 초과하면 분석 대상이 너무 광범위하다는 신호입니다. 모노레포라면 패키지 하나만 따로 열거나, 관심 있는 상위 폴더(예: src/)만 선택해 보세요. 자동 제외 목록에 없는 사내 산출물 폴더가 있다면 그 폴더를 제외하고 부모 폴더를 여세요.

AI 응답 관련

429 에러 (Rate Limit)

• 증상 — 분석 시 “요청이 너무 많습니다”라는 메시지가 표시됩니다.
• 원인 — Demo 모드의 공정 사용 한도 또는 API 공급자의 Rate Limit을 초과했습니다.
• 해결 — 잠시 기다렸다가 다시 시도하거나, API Key 모드 또는 Bridge 모드로 전환하세요. API Key 모드에서는 해당 공급자 콘솔에서 요금제를 상향할 수 있습니다.

500 에러 또는 빈 응답

• 증상 — 분석 중 “AI 응답을 받지 못했습니다”라는 에러가 발생합니다.
• 원인 — AI 제공사 서버의 일시적 장애, 또는 요청이 너무 커서 모델의 컨텍스트 한도를 넘었을 가능성이 있습니다.
• 해결 — Settings의 코드 구조 요약 크기를 줄여서(예: 250KB → 150KB) 다시 시도하세요. 반복된다면 다른 AI 모드로 전환해 보세요.

다이어그램이 이상하거나 부정확합니다

• 증상 — 생성된 다이어그램이 실제 구조와 맞지 않거나 누락이 많습니다.
• 원인 — 모델 품질 한계, 또는 코드 구조 요약 한도가 너무 작아 전체 구조가 모델에 전달되지 않았을 수 있습니다.
• 해결 — Settings에서 코드 구조 요약 크기를 늘리거나, 더 강력한 모델(예: API Key 모드의 Claude / GPT-4)을 사용해 보세요.

캐시 관련

수정한 코드가 반영되지 않습니다

• 증상 — 파일을 변경했는데 다이어그램이 그대로입니다.
• 원인 — 분석 결과는 브라우저에 캐시되어 같은 프로젝트를 다시 열 때 즉시 복원됩니다.
• 해결 — Settings 모달의 캐시 지우기 버튼으로 분석 캐시를 삭제한 뒤 다시 분석을 실행하세요.

캐시 지우기가 동작하지 않습니다

• 해결 — 브라우저의 사이트 데이터 삭제(Chrome: 설정 → 개인정보 및 보안 → 사이트 설정 → ropeman.dev)로 강제 초기화할 수 있습니다.

브라우저 호환성

Firefox / Safari에서 폴더를 열 수 없습니다

• 증상 — “폴더 열기” 버튼을 눌러도 폴더 선택 다이얼로그가 열리지 않습니다.
• 원인 — Firefox와 Safari는 File System Access API를 지원하지 않습니다.
• 해결 — 드래그 앤 드롭으로 폴더를 업로드하거나, Chrome/Edge 등 Chromium 기반 브라우저를 사용하세요.

WebGPU 모드가 동작하지 않습니다

• 증상 — WebGPU 모드 선택 시 “이 브라우저는 WebGPU를 지원하지 않습니다” 메시지가 표시됩니다.
• 원인 — 구버전 브라우저이거나 WebGPU가 비활성화되어 있습니다.
• 해결 — 최신 Chrome/Edge를 사용하고, chrome://gpu에서 WebGPU 상태를 확인하세요. VRAM이 부족한 기기에서는 모델 로드가 실패할 수 있습니다.

Bridge 모드에서 연결이 끊어집니다

• 해결 — Bridge 서버 터미널이 여전히 실행 중인지 확인하고, 포트가 다른 프로세스에 점유되지 않았는지 점검하세요. 자세한 내용은 Bridge 서버 설정을 참고하세요.

그 외

다이어그램 내보내기가 실패합니다

• 해결 — 브라우저가 Canvas 콘텐츠 저장을 허용하는지 확인하고, 시크릿 모드에서는 일부 저장 권한이 제한될 수 있으니 일반 창에서 시도해 보세요.

문제가 지속되면 브라우저 콘솔의 에러 메시지와 함께 [email protected]로 보내 주세요. 재현 경로가 포함되면 빠르게 대응할 수 있습니다.