어떤 버그들은 긴 경로(long path), Windows 머신, 그리고 서브프로세스(subprocess)를 생성하는 벡터 데이터베이스(vector database)가 결합될 때만 나타납니다. 이것은 왜 크로스 플랫폼(cross platform)이 정말 중요한지를 가르쳐준 어느 버그에 관한 이야기입니다.

자기소개

저는 콜카타 출신의 풀스택 및 AI 엔지니어인 Aniruddha Adak이며, GitHub 계정은 **@aniruddhaadak80**입니다. 저는 Python, Next.js, TypeScript 및 에이전트 프레임워크(agent frameworks)로 작업하는 것을 좋아합니다.

저의 오픈 소스 여정은 2024년 간단한 카드 추가로 시작되었으며, topoteretes/cognee, openclaw/openclaw, NousResearch/hermes-agent, google-gemini/gemini-cli와 같은 프로젝트 전반에 걸쳐 **29개 이상의 병합된 PR(merged PRs)**로 성장했습니다.

이 포스트는 DEV Summer Bug Smash 2026을 위한 Smash Stories 참여작입니다. 이것은 제가 가장 좋아하는 버그 수정 중 하나 뒤에 숨겨진 혼란스러운 이야기이며, Google Antigravity가 어떻게 제가 이를 해결하도록 도왔는지에 대한 이야기입니다.

배경, 오직 Windows 사용자에게만 나타나는 버그

상상해 보세요. 여러분은 Cognee를 사용하여 RAG 파이프라인(RAG pipeline)을 구축하고 있습니다. Mac과 Linux에서는 모든 것이 잘 작동합니다. 코드를 푸시하면 Windows를 사용하는 기여자가 테스트를 시도하고, 갑자기 OSError: [WinError 3] The system cannot find the path specified 에러가 발생합니다.

이 현상은 Cognee가 로컬 파일 시스템(filesystem)에 벡터 데이터(vector data)를 영구 저장(persist)하려고 할 때, LanceDB 내부에서 발생합니다.

이 문제는 cognee의 #2941 이슈였습니다. 이것은 무작위적인 에러가 아니었습니다. LanceDB가 서브프로세스(subprocesses)를 생성하는 방식과 충돌하는 체계적인 Windows의 제한 사항이었습니다.

Windows에는 260자로 제한된 레거시 MAX_PATH 제한이 있습니다. 경로가 길어지면 Windows에 긴 경로를 허용하도록 알리기 위해 경로 앞에 \?\를 접두사로 붙여야 합니다. 대부분의 Python 코드는 Unix에서는 이것이 전혀 필요하지 않기 때문에 이를 잊어버립니다.

Cognee는 C:\Users\aniruddha\projects\cognee\.data\vector_db\...와 같은 절대 경로(absolute paths)를 생성하여 LanceDB에 전달했고, LanceDB는 그보다 더 깊게 중첩된 파일들을 생성했습니다. 프로젝트 경로가 길어지면 최종 경로가 260자를 초과하게 되고, Windows는 이를 생성을 거부했습니다. 하지만 이는 오직 LanceDB가 서브프로세스(subprocess)에서 해당 경로에 접근하려고 할 때만 발생했습니다.

이는 CI(지속적 통합) 환경이 Ubuntu에서만 실행된다면 절대 나타나지 않을 종류의 버그입니다.

혼란, 그리고 이 버그를 포착하기 어려웠던 이유

이 버그는 여러 가지 이유로 포착하기 어려웠습니다. 우선 운영체제(OS) 특화적이었으며, 프로젝트 경로가 긴 Windows 환경에서만 나타났습니다. 또한 오류가 Cognee 코드에서 직접 발생하는 것이 아니라 LanceDB에서 발생했기 때문에 간접적이었습니다. 짧은 경로는 작동하고 긴 경로는 실패했기에 경로 의존적(path dependent)이었습니다. 마지막으로 메인 프로세스는 폴처를 생성할 수 있었지만, 자식 프로세스는 긴 경로 접두사(long path prefix) 없이는 해당 폴더를 볼 수 없었기에 서브프로세스(subprocess)와 관련이 있었습니다.

저는 많은 사용자가 유사한 문제를 보고하면서 LanceDB의 탓으로 돌리는 것을 보았습니다. 실제 해결책은 vector_db_url이 정규화(normalize)되는 Cognee 내부에 있어야 했습니다.

Antigravity와 Google AI를 활용한 접근 방식

이 지점이 제 워크플로우가 바뀐 부분입니다. 저는 전체 조사 과정에서 Gemini 2.5 Pro가 탑재된 **Antigravity 에이전트 기반 IDE (agentic IDE)**를 사용했습니다.

첫 번째 단계인 코드베이스 이해를 위해, 저는 Antigravity에 vector_db_url이 어디에서 생성되고 어떻게 LanceDB로 전달되는지 물었습니다. Antigravity는 설정(config)부터 LanceDB 어댑터(adapter)까지의 흐름을 단 몇 초 만에 추적했습니다.

두 번째 단계인 정신적 재현(reproducing mentally)을 위해, 저는 Gemini에게 Windows의 긴 경로 접두사 규칙과 절대 경로에 \?\가 필요한 경우를 설명해 달라고 요청했습니다. Gemini는 \?\ 및 \?\UNC\ 규칙을 설명하며, 먼저 os.path.abspath를 통해 정규화해야 한다고 알려주었습니다.

세 번째 단계인 수정 사항 작성 단계에서는, Antigravity에 Windows 절대 경로에 이미 접두사가 붙어 있지 않다면 안전하게 \?\를 붙여주고, 상대 경로와 Unix 경로는 건드리지 않는 헬퍼(helper) 함수를 만들도록 프롬프트를 입력했습니다. Antigravity는 os.name == 'nt' 체크를 사용하고 드라이브 문자 경로와 UNC 경로를 모두 처리할 것을 제안했습니다.

네 번째 단계인 Windows에서의 테스트를 위해, 저는 어떤 OS에서도 테스트 가능하도록 로직을 작성한 뒤, 나중에 Crabbox를 통해 Windows 가상 머신(VM)에서 이를 검증했습니다. 이는 제가 openclaw PR 90275에서 사용했던 것과 동일한 접근 방식입니다.

5단계인 예외 케이스(edge cases)를 위해, 저는 Gemini에게 예외 케이스 목록을 작성해 달라고 요청했습니다. Gemini는 명확한 목록을 제공했습니다. 이미 접두사(prefix)가 붙은 경로는 중복으로 접두사를 붙여서는 안 됩니다. 상대 경로(Relative paths)는 그대로 두어야 합니다. Unix 경로는 그대로 두어야 합니다. UNC 경로는 \?\UNC\ 처리가 필요합니다. None 또는 빈 문자열은 안전하게 처리되어야 합니다.

이러한 협업 덕분에 수정 사항이 견고해졌으며, 이것이 제가 Google AI의 최적 활용(Best Use of Google AI) 부문에 제출하는 이유입니다.

병합된 수정 사항

제가 병합한 PR은 cognee의 fix(lancedb): 긴 경로에 대한 OS Error 3를 해결하기 위해 Windows 경로에 자동으로 접두사 추가입니다. PR 링크는 https://github.com/topoteretes/cognee/pull/3123이며, 현재 병합되어 릴리스되었습니다.

현재 코드가 작동하는 방식

import os

def normalize_vector_db_url(url: str) -> str:
...

그 후, LanceDB 연결을 구축할 때 이 정규화된(normalized) 경로가 사용됩니다. 이제 서브프로세스(subprocess)는 Windows가 긴 경로가 활성화된 것으로 인식하는 경로를 전달받게 됩니다.

간단히 말해서, 우리는 Windows에 이 경로는 길어도 괜찮으니 차단하지 말라고 명시적으로 알려주는 것입니다.

수정 전후 비교

이 수정 전에는 프로젝트 구조가 깊은 Windows 환경에서 lancedb 서브프로세스가 OS Error 3와 함께 실패했습니다. 이 수정 후에는 경로에 접두사가 자동으로 붙기 때문에 동일한 구조에서도 정상 작동합니다. 사용자의 별도 조치는 필요하지 않습니다. 사용자에게 보이지 않는 것, 그것이 가장 좋은 종류의 수정입니다.

이 이야기를 만든 다른 병합된 버그 수정들

이것이 저의 유일한 Windows 관련 전투는 아니었습니다. 여기에는 교차 플랫폼(cross platform) 사고방식을 가르쳐준 제가 병합한 모든 버그 관련 PR들이 있습니다. 모두 병합된 것들뿐이며 초안(drafts)은 포함되지 않았습니다.

실전에서의 교훈

크로스 플랫폼 (Cross platform) 버그는 실재하는 버그입니다. 만약 당신의 라이브러리가 Windows에서 작동한다고 주장한다면, Windows에서 파일 경로를 테스트하십시오. 서브프로세스 (Subprocesses)는 서로 다른 경로 규칙을 가집니다. 당신의 Python 프로세스에서 작동하는 것이 자식 프로세스 (child process)에서는 실패할 수 있습니다. 2026년에도 긴 경로 (Long paths) 문제는 여전히 존재합니다. 많은 도구들이 여전히 MAX_PATH 제한에 걸립니다. AI는 디버깅을 대체하는 것이 아니라, 디버깅을 가속화합니다. Gemini는 제가 코드를 매핑하고 엣지 케이스 (edge cases)를 나열하는 데 도움을 주었지만, 저는 여전히 Windows 내부 구조 (internals)를 이해해야 했습니다. 작은 수정이 큰 영향을 미칩니다. 이 20줄짜리 헬퍼 (helper) 코드는 중첩된 프로젝트를 사용하는 모든 Windows 사용자의 막힌 길을 뚫어주었습니다.

Antigravity가 어떻게 나의 디버깅 파트너가 되었나

이번 챌린지가 **Google AI의 최적 활용 (Best Use of Google AI)**을 요구하기 때문에, 저의 환경에 대해 명확히 말씀드리고 싶습니다. 저는 오픈 소스 기여를 위한 일상적인 IDE로 Antigravity를 사용합니다. 저는 그 안에서 Gemini 2.5 Pro를 사용하여 코드베이스 검색 및 호출 그래프 (call graph) 분석, 재현 스크립트 작성, 엣지 케이스를 위한 테스트 케이스 생성, 그리고 메인테이너(maintainers)들이 좋아하는 PR 설명 초안 작성을 수행합니다.

이번 cognee 버그의 경우, Antigravity는 탐색 시간을 몇 시간에서 몇 분으로 단축해 주었습니다. 덕분에 파일을 찾아 헤매는 대신 실제 Windows 로직에 집중할 수 있었습니다.

저는 AI와 함께 빌드하지만, 책임감을 가지고 배포합니다. 모든 코드는 병합되기 전에 제가 직접 검토합니다.

마치며

이 버그는 가장 전설적인 버그들은 요란하지 않다는 것을 가르쳐 주었습니다. 그것들은 조용하며, 단 하나의 OS, 단 하나의 조건에서만 나타나고, 사용자로 하여금 자신이 무언가 잘못했다고 생각하게 만듭니다.

기여자로서 저의 역할은 사용자가 그렇게 생각하지 않도록 만드는 것입니다.

만약 당신이 이 글을 읽고 있고 파일 시스템을 다루는 라이브러리를 개발하고 있다면, 제발 Windows에서 긴 경로로 테스트해 보십시오. 당신이 무엇을 발견하게 될지 놀라게 될 것입니다.

링크 및 크레딧

GitHub는 [https://github.com/aniruddhaadak80]입니다
병합된 수정 사항은 [https://github.com/topoteretes/cognee/pull/3123]입니다
수정된 이슈는 [https://github.com/topoteretes/cognee/issues/2941]입니다
챌린지 페이지는 [https://dev.to/bugsmash]입니다