Brierly docs
v1.0.0
Get help
● Ship

Troubleshooting
common problems and fixes.

Cases from the code and the build, with what to check.

questionssourcepurchasesserverbuild

01The app shows no questions

  1. Was the app built with --dart-define=API_BASE_URL=https://...? Without it the app never contacts a server and shows an empty state.
  2. Is the address https and reachable from the phone? Open https://your-server/healthz in the phone's browser.
  3. Does the server have questions? Run curl https://your-server/v1/questions. An empty list means the source returned nothing that passed your filters, or the server cannot reach the source (below).
  4. Is "Market questions" switched off under App config: features? Then only custom questions show.

02The server cannot reach the question source

Console Overview shows a warning "Market source reachable and filled". Run the curl test on your host (Test the source from your host). If it times out, your host's network or provider blocks it: try another host. The optional second provider is blocked in some countries and by some providers; if it fails from your host, switch back to the default or to None and use custom questions.

03Too few or unsuitable market questions

Lower the minimum bettors or volume, widen the topic list, or raise the horizon (days) under Market data source, then press refresh on the Questions page. If an unsuitable question slips through, press Hide on it and add its words to the "never these words" list.

04The phone cannot connect to my test server

The project allows https only. An address starting with http://, such as a local test server, is refused by current Android and iOS. Use a deployed server or an https tunnel for device tests.

05The crowd's odds did not appear after I sealed

If the server could not be reached at that moment, the call is sealed and the odds are fetched when possible. If they arrive more than 60 minutes after sealing, they are shown but do not count in the you-versus-crowd numbers (You vs the crowd).

06The paywall says purchases are not set up

No product id is set for this platform. Fill the ids in brand.dart or the console (Where to put the ids). Ids must match App Store Connect and Play Console exactly.

07Products are set but the store returns nothing

iOS: the Paid Apps agreement and tax forms must be complete and the product ready to submit. Android: the app must be installed from a Play test track (not a sideloaded APK) by a licence tester, and the product and base plan must be active. Wait some hours after creating products.

08Purchase verification answers 501

501 verification_off means verification is not switched on in the console, so the app trusts the on-device result. Turn it on under Purchases and fill in the credentials.

09Google Play verification fails with a permission error

The service account must be invited in Play Console with View app information and View financial data, and the Android Publisher API must be enabled in the Google Cloud project. New permissions can take some time to apply.

10App Store lookup fails

Check the bundle id, Key ID, Issuer ID, and that the .p8 text was pasted whole including its BEGIN and END lines. The server tries Production, then Sandbox.

11I cannot find the console setup code

It is printed in the server log at start when ADMIN_SETUP_TOKEN is empty. In Docker run docker logs. Or set ADMIN_SETUP_TOKEN in .env and restart.

12npm ci finishes but better-sqlite3 does not load (npm 11)

The server stores its data with better-sqlite3, a native module that must run an install script. Newer npm versions (the author hit this on npm 11.20) can block install scripts until you approve them, and the server then fails to start with an error about the sqlite binding. Fix, run inside server/:

Windows users

Flutter runs natively on Windows: use PowerShell for the flutter commands and Android builds (iOS builds need a Mac). For the server, either install Node.js 22.12+ for Windows and use PowerShell (replace cp .env.example .env with Copy-Item .env.example .env; there is no openssl by default, so use WSL or any random 64-character hex string), or run the commands in WSL 2 (Ubuntu) or Docker. macOS and Linux users can ignore this note.

npm install-scripts approve better-sqlite3
npm rebuild better-sqlite3
npm run build
npm start

If your npm reports that the command does not exist, follow the message it prints for allowing the better-sqlite3 build script (the exact name differs between npm versions), then run npm rebuild better-sqlite3. This entry comes from the author's experience; it was not reproduced here, where npm 10.9.7 ran the script without being asked (unverified on npm 11).

13npm ci fails or the server will not start

Use Node 22.12 or newer (node -v; 26 recommended). better-sqlite3 is a native module: if no prebuilt file exists for your system, you need build tools (Python 3, make, a C++ compiler). Delete node_modules and run npm ci again after changing Node versions.

14429 errors, or everyone shares one address

/v1 routes allow 60 requests a minute per address. Behind a proxy set TRUST_PROXY_HOPS=1, otherwise all users look like the proxy's address.

15A console change does not appear in the app

The config is cached for 5 minutes and by ETag. Wait, then reopen the app. The question list is cached for 60 seconds. Check the app was built with API_BASE_URL and that the address is https and reachable from the phone.

16Play rejects the upload or says the app is debug-signed

As shipped, release builds use the debug key. Add your own signing config (Release).

17Xcode says signing failed or the bundle id is not available

The project ships with no team set. Choose your own team and a bundle id you own (Rename).

18iOS build fails on a pod deployment target

The Podfile platform is 16.0. Keep it at 16.0 or higher, then run pod install again.