Polymarket troubleshooting

Windows와 WSL 2

여기의 모든 항목은 00 Setup의 지원되는 Windows 환경, 즉 Docker Desktop WSL 통합이 적용된 WSL 2의 Ubuntu를 전제로 합니다.

PowerShell에서 명령이 "not recognized"라고 나온다

증상: PowerShell이 ./preflight.sh, source, export 또는 다른 워크샵 명령을 거부합니다.

원인: PowerShell은 Module 00에 표시된 WSL 부트스트랩에만 사용합니다. 모든 워크샵 명령은 Ubuntu 안에서 실행됩니다.

시작 메뉴에서 Ubuntu를 열고, 랩 디렉터리로 돌아가서 환경 파일을 다시 source하세요. 새 셸은 그것을 상속하지 않습니다:

cd "$(git rev-parse --show-toplevel)/workshop_public/polymarket"
set -a; source ./.env.polymarket; set +a
./preflight.sh

리포지토리가 `/mnt/c` 아래에 있다

증상: Docker 바인드 마운트가 느리거나, ./preflight.sh가 권한 오류를 보고하거나, pwd가 /mnt/c/Users/로 시작합니다.

원인: 클론이 WSL의 Linux 파일 시스템이 아니라 Windows 파일 시스템에 놓였습니다.

Linux 홈 디렉터리에 새로 클론하고, 작성해 둔 .env.polymarket 외에는 아무것도 옮기지 마세요:

cd ~
git config --global core.autocrlf input
git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd "$(git rev-parse --show-toplevel)/workshop_public/polymarket"
cp .env.polymarket.example .env.polymarket

Ubuntu가 WSL 1로 실행되고 있다

증상: wsl --list --verbose가 Ubuntu를 VERSION 1로 표시하거나, Docker Desktop이 해당 배포와 통합하지 못합니다.

PowerShell을 관리자로 실행한 상태에서:

wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose

Ubuntu 안에서 `docker`를 쓸 수 없다

증상: Docker Desktop은 실행 중인데 Ubuntu가 docker: command not found를 보고하거나 데몬에 도달할 수 없습니다.

Docker Desktop -> Settings -> General -> Use the WSL 2 based engine와 Settings -> Resources -> WSL Integration -> Ubuntu를 활성화하고 변경을 적용한 뒤, PowerShell에서 wsl --shutdown을 실행하고 Ubuntu를 다시 여세요. 그러면 docker version이 Client와 Server 섹션을 모두 표시해야 합니다. apt로 두 번째 Docker Engine을 설치하지 마세요.

WSL 또는 Docker의 메모리가 부족하다

증상: collector 컨테이너가 종료되거나 재시작 루프에 빠지고, docker compose ... up --build가 중간에 실패하거나, docker info --format '{{.MemTotal}}'가 4 GB보다 훨씬 낮게 보고합니다.

원인: Docker Desktop의 WSL 2 백엔드는 WSL 가상 머신에 의해 제한되며, 그 기본 한도는 호스트 RAM의 일부이고 다른 배포가 함께 실행되는 장비에서는 작을 수 있습니다.

Docker Desktop을 닫고, PowerShell을 열어 명시적 한도를 설정하세요:

@('[wsl2]', 'memory=4GB', 'processors=2') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown

Docker Desktop을 시작하고, Ubuntu를 다시 열고, .env.polymarket을 다시 source한 뒤 ./preflight.sh를 다시 실행하세요.

스크립트가 `/usr/bin/env: 'bash\r': No such file or directory`를 보고한다

증상: ./preflight.sh가 즉시 실패하고 오류에 bash\r 또는 ^M이 포함됩니다.

원인: Windows CRLF 줄바꿈이 리포지토리에 필요한 LF 줄바꿈을 대체했습니다. 보통 클론할 때 core.autocrlf가 true였기 때문입니다.

git config --global core.autocrlf input
git status --short
git add --renormalize .

무엇이든 버리기 전에 git status를 확인하세요. 체크아웃에 필요한 작업이 없다면 ~/ClickHouse_Demos에 새로 클론하는 것이 가장 안전한 복구입니다.

환경 파일에 Windows 줄바꿈이 들어 있다

증상: printf는 그럴듯한 호스트를 표시하는데 ./preflight.sh나 clickhouse client가 이를 해석하지 못하거나, 눈에 보이는 이유 없이 TLS 핸드셰이크가 실패합니다.

원인: .env.polymarket이 Windows 편집기로 저장되어 모든 값이 캐리지 리턴으로 끝납니다. set -a; source가 이를 유지하므로 CLICKHOUSE_HOST가 host\r이 됩니다.

sed -i 's/\r$//' .env.polymarket
set -a; source ./.env.polymarket; set +a
printf 'host=[%s]\n' "$CLICKHOUSE_HOST"
./preflight.sh

예상 결과: 닫는 대괄호가 호스트 이름 바로 뒤, 같은 줄에 있습니다. 이제부터는 Ubuntu 안에서 파일을 편집하세요.

헬스 엔드포인트가 Windows 브라우저에서 열리지 않는다

증상: Ubuntu에서는 curl http://localhost:8090/health가 동작하지만, 같은 URL이 Windows 브라우저에서는 실패합니다.

원인: WSL의 localhost 포워딩은 부팅 단위로 설정되며, 절전 이후나 wsl --shutdown 이후에 끊길 수 있습니다.

먼저 Ubuntu에서 포트를 확인하세요. 그래도 브라우저가 접근하지 못하면 PowerShell에서 wsl --shutdown을 실행하고 Ubuntu를 다시 여세요:

curl --fail --silent http://localhost:8090/health | python3 -m json.tool

이 워크샵의 모든 검증 단계에서 권위 있는 기준은 터미널이며, 브라우저는 편의 수단입니다.

강의실 네트워크가 Polymarket을 차단한다

증상: preflight가 Gamma에 도달하지 못하거나, 헬스가 소스 오류와 함께 degraded에 머무릅니다.

sed -i.bak 's/^POLYMARKET_MODE=.*/POLYMARKET_MODE=fixture/' .env.polymarket
set -a; source ./.env.polymarket; set +a
docker compose --env-file .env.polymarket up -d --build --force-recreate collector
curl --fail --silent http://localhost:8090/health | python3 -m json.tool

예상 결과: status가 fixture이고, 데이터가 5초마다 늘어납니다.

헬스가 `websocket_stale_rest_active`라고 나온다

last_trade_reconcile_at와 last_book_fallback_at가 계속 전진한다면 복구 가능한 상태입니다. collector는 백오프를 두고 재연결합니다. 반복해서 재시작하지 마세요.

docker compose --env-file .env.polymarket logs --tail=50 collector
sleep 35
curl --fail --silent http://localhost:8090/health | python3 -m json.tool

두 REST 타임스탬프가 모두 null이거나 오래된 상태로 남아 있을 때만 픽스처 모드를 사용하세요.

헬스가 `clickhouse_write_retrying` 또는 `clickhouse_write_stalled`라고 나온다

프로세스가 실행 중인 동안 해당 배치는 메모리에 남아 같은 중복 제거 토큰으로 재시도됩니다. Cloud 값을 수정하고 파일을 source한 뒤 collector를 재생성하세요:

${EDITOR:-vi} .env.polymarket
set -a; source ./.env.polymarket; set +a
./preflight.sh
docker compose --env-file .env.polymarket up -d --force-recreate collector

테이블을 드롭하지 마세요. 재시도는 안전합니다.

강제 재생성은 아직 메모리에만 있던 호가 tick을 버립니다. 재시작된 collector는 REST를 통해 현재 book을 다시 채우고, 마지막으로 확인 응답된 체크포인트부터 공개 거래를 정합화합니다. 이 워크샵은 내구성 있는 로컬 큐를 제공한다고 주장하지 않습니다.

`missing ClickHouse tables`가 나타난다

Module 02를 건너뛰었거나 다른 서비스를 대상으로 실행했습니다. 현재 파일을 source하고 확인하세요:

set -a; source ./.env.polymarket; set +a
clickhouse client \
  --host "$CLICKHOUSE_HOST" \
  --port "$CLICKHOUSE_PORT" \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --secure \
  --query "SHOW TABLES FROM polymarket"

객체가 하나라도 없으면 Module 02로 돌아가세요.

급변동 종목 쿼리가 비어 있다

이 쿼리는 5분 경계 양쪽에 관측치가 있어야 합니다. collector가 최소 6분간 실행될 때까지 기다리거나, 시간이 정해진 수업에서는 픽스처 모드를 사용하세요.

포트 8090이 이미 사용 중이다

.env.polymarket의 POLYMARKET_HEALTH_PORT를 변경하고, source한 뒤 재생성하세요:

sed -i.bak 's/^POLYMARKET_HEALTH_PORT=.*/POLYMARKET_HEALTH_PORT=8091/' .env.polymarket
set -a; source ./.env.polymarket; set +a
docker compose --env-file .env.polymarket up -d --force-recreate collector
curl --fail --silent http://localhost:8091/health | python3 -m json.tool