Polymarket troubleshooting

Windows and WSL 2

Every entry here assumes the supported Windows environment from 00 Setup: Ubuntu on WSL 2 with Docker Desktop WSL integration.

A command is "not recognized" in PowerShell

Symptom: PowerShell rejects ./preflight.sh, source, export, or another workshop command.

Cause: PowerShell is used only for the labelled WSL bootstrap in Module 00. Every workshop command runs inside Ubuntu.

Open Ubuntu from the Start menu, return to the lab directory, and re-source the environment file -- a new shell does not inherit it:

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

The repository is under `/mnt/c`

Symptom: Docker bind mounts are slow, ./preflight.sh reports a permission error, or pwd begins with /mnt/c/Users/.

Cause: the clone landed on the Windows filesystem instead of WSL's Linux filesystem.

Clone a clean copy in your Linux home directory and carry across nothing but your filled .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 is running as WSL 1

Symptom: wsl --list --verbose shows Ubuntu with VERSION 1, or Docker Desktop cannot integrate with the distro.

In PowerShell as Administrator:

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

`docker` is unavailable inside Ubuntu

Symptom: Docker Desktop is running, but Ubuntu reports docker: command not found or cannot reach the daemon.

Enable Docker Desktop -> Settings -> General -> Use the WSL 2 based engine and Settings -> Resources -> WSL Integration -> Ubuntu, apply the change, run wsl --shutdown in PowerShell, then reopen Ubuntu. docker version must then show both a Client and a Server section. Do not install a second Docker Engine with apt.

WSL or Docker runs out of memory

Symptom: the collector container is killed or restart-loops, docker compose ... up --build fails part way, or docker info --format '{{.MemTotal}}' reports well under 4 GB.

Cause: Docker Desktop's WSL 2 backend is bounded by the WSL virtual machine, whose default limit is a fraction of host RAM and can be small on a machine with other distros running.

Close Docker Desktop, open PowerShell, and set an explicit limit:

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

Start Docker Desktop, reopen Ubuntu, re-source .env.polymarket, and run ./preflight.sh again.

A script reports `/usr/bin/env: 'bash\r': No such file or directory`

Symptom: ./preflight.sh fails immediately and the error contains bash\r or ^M.

Cause: Windows CRLF line endings replaced the repository's required LF endings, usually because core.autocrlf was true when you cloned.

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

Review git status before discarding anything. If the checkout holds no work you need, a clean clone under ~/ClickHouse_Demos is the safest recovery.

The environment file has Windows line endings

Symptom: printf shows a plausible host, but ./preflight.sh or clickhouse client cannot resolve it, or the TLS handshake fails for no visible reason.

Cause: .env.polymarket was saved by a Windows editor, so every value ends with a carriage return. set -a; source keeps it, and CLICKHOUSE_HOST becomes host\r.

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

Expected: the closing bracket sits immediately after the hostname, on the same line. Edit the file inside Ubuntu from now on.

The health endpoint does not open in the Windows browser

Symptom: curl http://localhost:8090/health works in Ubuntu, but the same URL fails in the Windows browser.

Cause: WSL localhost forwarding is established per boot and can lapse after a sleep or a wsl --shutdown.

Confirm the port from Ubuntu first; if the browser still cannot reach it, run wsl --shutdown in PowerShell and reopen Ubuntu:

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

The terminal is authoritative for every verification step in this workshop; the browser is a convenience.

The classroom network blocks Polymarket

Symptom: preflight cannot reach Gamma, or health stays degraded with source errors.

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

Expected: status is fixture; data grows every five seconds.

Health says `websocket_stale_rest_active`

This is recoverable when last_trade_reconcile_at and last_book_fallback_at keep advancing. The collector reconnects with backoff. Do not restart it repeatedly.

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

Use fixture mode only if both REST timestamps remain null or stale.

Health says `clickhouse_write_retrying` or `clickhouse_write_stalled`

While the process is running, the exact batch remains in memory and retries with the same deduplication token. Fix the Cloud values, source the file, then recreate the 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

Do not drop the tables; a retry is safe.

A forced recreate discards any quote ticks that were still only in memory. The restarted collector repopulates current books through REST and reconciles public trades from the last acknowledged checkpoint. The workshop does not claim a durable local queue.

`missing ClickHouse tables` appears

Module 02 was skipped or ran against another service. Source the current file and check:

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"

Return to Module 02 if an object is missing.

The mover query is empty

It requires observations on both sides of a five-minute boundary. Wait until the collector has run for at least six minutes, or use fixture mode for a timed class.

Port 8090 is already in use

Change POLYMARKET_HEALTH_PORT in .env.polymarket, source it, and recreate:

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