Troubleshooting
errors and their fixes.
Most messages appear in the app's log: the terminal in a local install, or journalctl -u receipts -f on a server. Tip: paste the exact error into the search box.
01Start and install
"EADDRINUSE: address already in use :::8787"
Another program (often an older copy of Receipts) uses the port. Find it with sudo lsof -i :8787 and stop it, or set another PORT and point your proxy at it.
The install fails while building better-sqlite3
Install build tools (macOS xcode-select --install; Ubuntu sudo apt install -y build-essential python3) and run the install again.
"process.loadEnvFile is not a function"
Node is older than 20.12. Install Node 22 LTS.
"ADMIN_SECRET_KEY is not set. Using a generated key in …"
Not an error, but move that key into .env as ADMIN_SECRET_KEY and back it up: without it the secrets saved in the console cannot be read.
"DeprecationWarning: The punycode module is deprecated"
Printed by Node 22 because of a dependency. Harmless; nothing to do.
I lost the setup code
Restart the app: a new code is printed on every start until it is used. If you claimed the site but not the console yet (or the other way round), the new code works for the one still missing.
02Prices and signals
A signal never fills / no candles for a symbol
Usually the symbol or venue is wrong. The log shows lines starting with [pricing]. Write the symbol exactly as the venue does (ETHUSDT, not ETH/USDT) and check it is listed on that market. Test from the server:
curl "https://api.binance.com/api/v3/klines?symbol=ETHUSDT&interval=1m&limit=1"
curl "https://fapi.binance.com/fapi/v1/klines?symbol=ETHUSDT&interval=1m&limit=1"
curl "https://api.bybit.com/v5/market/kline?category=linear&symbol=ETHUSDT&interval=1&limit=1"A symbol the venue does not list is refused before sealing. If a symbol stops trading, the signal resolves as not filled six hours after expiry.
Binance answers HTTP 451 (or 403)
Binance blocks its API from some regions, depending on where your server is. Move the server to a region Binance serves, or have providers publish on bybit-spot / bybit-linear. Run the curl tests from the server before you decide.
OpenTimestamps calendars unreachable
The batch is still sealed; only the Bitcoin timestamp is missing. The error is saved with the batch (Anchors) and the anchor job retries. Seal a batch now also retries. Allow outbound HTTPS, or set OTS_CALENDARS to calendars you can reach.
03Stripe webhook
| Stripe shows | Cause and fix |
|---|---|
| 503 "Stripe webhooks are not configured" | STRIPE_WEBHOOK_SECRET is empty, or you did not restart after setting it. |
| 400 "webhook signature mismatch" | The secret does not belong to this endpoint. Test and live endpoints, and the Stripe CLI, each have their own whsec_. |
| 400 "missing Stripe-Signature" | Something other than Stripe called the address, or a proxy removed the header. |
| 400 "webhook timestamp outside tolerance" | The server clock is more than 5 minutes off: sudo timedatectl set-ntp true. |
200 with "handled":false | Delivered but not for a Receipts payment (another product on the same Stripe account), or an event Receipts does not use. Harmless. |
04Payments
"Members have a way to pay" warning in Status
No card, bank or crypto method is set up. Add Stripe keys, or switch on Bank transfer with instructions, or Stablecoins with at least one wallet.
"Every wallet address matches its network" is a blocker
A wallet address does not fit its network: EVM networks need 0x + 40 hex characters; Tron needs a T… address.
"Coupons work with bank and crypto payments"
Coupons do not apply to card payments. Remove the coupon to pay by card, or pay by bank or crypto.
A member paid but has no access
Bank and crypto payments wait under Payments to confirm until you approve them. Card payments need the invoice.paid webhook to arrive.
05Telegram
The bot does not react in the group
It must be an administrator of the group. If it still ignores /connect, send /connect@YourBotName, or turn off privacy mode in @BotFather (/setprivacy → Disable), then remove and re-add the bot. Only a linked provider account can connect a group. After a group becomes a supergroup its id changes: send /connect again.
Subscribers do not get invites
The subscriber must link Telegram, the provider must have a connected group and Pro (when charged), and the bot needs the "Invite users via link" right. Errors appear in the log as telegram grant for subscription ….
/long does nothing in the group
Publishing commands work only in a private chat with the bot.
06Accounts and pages
"Form expired" after submitting a form
The page was open too long or cookies are blocked. Reload and submit again.
Login says "Too many attempts"
10 failed attempts from one address within 15 minutes. Wait. Behind a proxy set TRUST_PROXY=1, or every visitor shares the proxy's address.
"This site is being set up. Only the operator email set in ADMIN_EMAIL can create the first account."
The operator has not been claimed yet. Sign up with the ADMIN_EMAIL address, or the setup code from the log.
Push notifications do not arrive
The member must allow notifications in the browser, and Admin → Delivery → Web push must be on. Push needs HTTPS (or localhost).