Polymarket トラブルシューティング

セットアップ、ソース、collector、ClickHouse の障害に対する正確な復旧手順。

Windows と WSL 2

ここに挙げる項目はすべて、00 セットアップでサポート対象とした Windows 環境、つまり Docker Desktop の WSL 統合を有効にした WSL 2 上の Ubuntu を前提とします。

PowerShell でコマンドが「認識されない」

症状: PowerShell が ./preflight.sh、source、export、その他のワークショップのコマンドを拒否する。

原因: PowerShell はモジュール 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/ で始まる。

原因: clone 先が WSL の Linux ファイルシステムではなく Windows のファイルシステムになっています。

Linux のホームディレクトリにクリーンなコピーを clone し、記入済みの .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 で 2 つ目の Docker Engine をインストールしないでください。

WSL または Docker がメモリ不足になる

症状: collector のコンテナが kill されるか再起動を繰り返す、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 が含まれる。

原因: リポジトリが要求する LF の改行が Windows の CRLF に置き換わっています。多くの場合、clone 時に core.autocrlf が true だったためです。

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

何かを破棄する前に git status を確認してください。チェックアウトに必要な作業が残っていない場合は、 ~/ClickHouse_Demos にクリーンな clone を作るのが最も安全な復旧策です。

環境ファイルが 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

fixture モードを使うのは、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 を通じて現在の板を取り直し、最後に確認応答されたチェックポイントから公開取引を突合します。このワークショップはローカルに耐久性のあるキューがあるとは主張していません。

`missing ClickHouse tables` が表示される

モジュール 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"

不足しているオブジェクトがあればモジュール 02 に戻ってください。

値動きのクエリが空になる

このクエリは 5 分の境界の両側に観測値があることを必要とします。collector を少なくとも 6 分動かすか、時間の制約がある授業では fixture モードを使ってください。

ポート 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