Troubleshooting
symptom, cause, fix.
The common problems, in the order people usually meet them.
01Admin: "ADMIN_SECRET_KEY is not set"
Run cd admin && npm run init. It writes admin/.env once and never overwrites an existing key. If you restored a backup, put your old .env back instead: a new key cannot decrypt secrets stored under the old one.
02Admin: port 8811 already in use
PORT=8812 npm startOr add PORT=8812 to admin/.env.
03Admin: lost the one-time setup code
Restart the admin. While no owner exists, every start prints a new code, and any printed code works until the owner is created.
04npm install fails while building better-sqlite3
No prebuilt binary exists for your platform, so it compiles from source. Install a C++ toolchain (macOS: xcode-select --install) and run npm install again. Unverified on platforms other than macOS.
05Scanner: "Could not load board.json"
- You opened the HTML file directly. Browsers block
fetch()fromfile://. Serve the folder:python3 -m http.server 8777. - The file is missing. Run the refresh job and pull, or check that
scanner/public/board.jsonwas deployed.
06A venue is "unavailable" or a fetch fails
A network that blocks a domain often looks like an ordinary connection or TLS error. Some internet providers block Polymarket's domains. Do not try to get around a block. The refresh job runs on GitHub's runners, which are not behind your provider; the workflow log's "Probe venue reachability" step shows what the runner sees.
07Kalshi answers 403
The request carried an Origin header, which any browser page sends. Fetch Kalshi only from the job. Do not add a browser call to Kalshi.
08Polymarket host does not resolve
clob-v2.polymarket.com had no public DNS record when checked (2026-09-22). Use https://clob.polymarket.com in Venues → Polymarket CLOB host and, if you set it, in POLYMARKET_CLOB_HOST.
09The pages show old data
- The schedule is off by default: the data is from the last manual run (turn it on).
- Your host did not redeploy after the job's commit. On Vercel's Hobby plan, commits by the job's bot author are not deployed (why and what to do).
- A CDN caches JSON: set
Cache-Control: no-storefor*.json. - GitHub paused the schedule on a quiet repository; re-enable it in the Actions tab.
10A setting does not appear on the live site
- Is
config/public.jsoncommitted and deployed? The admin writes the file; it does not deploy. - Is it reachable at
/config/public.jsonon your site? - Is Status →
publicConfiggreen? - Is the value valid? The pages ignore an accent that is not
#rgb/#rrggbb, a logo that is not an http(s) ordata:imageURL, and a channel link that is not a valid URL.
11The refresh workflow fails
| Failing step | Meaning |
|---|---|
| Build board | The Scanner job crashed; the log shows the error. A venue outage alone does not crash it. |
| Fail if the run fabricated anything | A data integrity rule was broken. Do not bypass it. |
| Read the Terminal tape from Polygon | Every RPC failed (yours, if set, then the three public ones). Usually temporary; run again. "POLYGON_RPC_URL is not a valid URL" or "must be https://" means the secret is malformed; the value is never printed. With POLYGON_RPC_ONLY=1 there is no public fallback. |
| Commit the new board | Push refused: check workflow permissions, or a concurrent push (run again). |
12"0 positive after fees" or "0 candidates"
This is the real result, not a fault. scanner/public/crossvenue-diag.json lists the veto counts and the highest-scoring rejected pairs with their reasons.
13Status: live builder fee warning with a network error
The feeLive check calls Polymarket from your machine and cannot succeed on a network that blocks it. It is a warning, not a blocker.