Troubleshooting

The problems people actually hit when running or deploying BabyMart, and how to fix each one.

Most problems come from three places: a missing environment variable, an API address the app can’t reach, or a Stripe webhook that never arrives. Start from the symptom you see.

flowchart TD
  S[Something is broken] --> Q1{Does the API start?}
  Q1 -- No --> A1["Check MONGO_URI and JWT_SECRET"]
  Q1 -- Yes --> Q2{Do the apps reach it?}
  Q2 -- No --> A2["Check the API URL variables and CORS"]
  Q2 -- Yes --> Q3{Are payments stuck?}
  Q3 -- Yes --> A3["Check the webhook path and secret"]
  Q3 -- No --> A4[See the sections below]

Starting the project

Port already in use

The storefront uses 3000, the admin 5173, the API 8000 and the docs 3002. Find and stop the process holding the port:

lsof -i :8000
kill <PID>

You can also move the API by setting PORT in apps/api/.env. If you do, update NEXT_PUBLIC_API_URL and VITE_NEXT_PUBLIC_API_URL to match.

`Cannot find module '@babyshop/types'` or missing types

@babyshop/types and @babyshop/config are imported from their compiled dist/ folders, which a fresh clone doesn’t have. Build them:

pnpm build:packages

The docs say “Dev server already running”

Astro allows one dev server per project. Stop the old one, then start again:

pnpm --filter @babyshop/docs astro dev stop
pnpm dev:docs

API

`Environment validation failed` on startup

The API checks its variables against a schema at boot (apps/api/src/config/env.ts) and lists the ones that are wrong. MONGO_URI and JWT_SECRET are required. In production you can also see JWT_SECRET must be at least 32 characters in production. Generate a longer secret:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

`MongoDB Connection Error` and the process exits

The connection string is wrong, or Atlas is blocking your IP address.

Check MONGO_URI in apps/api/.env, including the user, the password (URL-encode special characters) and the database name.
In Atlas → Network Access, add your current IP address. Vercel deployments need 0.0.0.0/0.

The connection is not awaited, and a failed connection calls process.exit(1) (apps/api/config/db.ts). That is why the API stops right after it starts.

`Not allowed by CORS`

The browser’s origin is not in the API’s allowlist. In development every origin is allowed. Otherwise set CLIENT_URL (storefront) and ADMIN_URL (admin) on the API to the exact origins: scheme, host and port, with no trailing slash. The list is built in apps/api/src/app.ts› createApp.

Too many requests (429)

The API allows 300 requests a minute per IP, and 10 a minute for login, register, OAuth and password-reset routes. Wait a minute. In tests, restart the API to reset the counters.

Storefront and admin

The admin shows a full-page Firebase error

The admin won’t start without its Firebase web config, even if you only use email sign-in. Add every VITE_FIREBASE_* key to apps/admin/.env and restart pnpm dev:admin. See Environment variables.

The admin throws on load about the API URL

VITE_NEXT_PUBLIC_API_URL is missing. Set it to the API’s address without /api, for example http://localhost:8000.

The deployed admin can’t reach the API

The browser console shows Refused to connect … Content Security Policy. Add your API’s origin to connect-src in apps/admin/vercel.json. See Deployment.

The storefront home page is empty

The database has no products. Import the demo catalogue with node scripts/seed-data.js (Demo data).

Payments

Checkout doesn’t redirect to Stripe

STRIPE_SECRET_KEY (server) or NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is missing from apps/web/.env. Restart the storefront after adding them.

Orders stay `pending` after a successful payment

The order is only marked paid when a webhook arrives and its signature checks out.

Locally, run stripe listen. Forward to the storefront with pnpm webhook:web, and to the API with pnpm webhook:api (localhost:8000/api/payments/webhook).
Copy the whsec_… secret that stripe listen prints into the receiving app’s STRIPE_WEBHOOK_SECRET. Test-mode secrets only work with test-mode keys.
In production, make sure the endpoint URLs in the Stripe dashboard match Deployment → Stripe in live mode.

The success page also asks the API to verify the session itself, so a missed webhook can still mark the order paid when the customer lands on /success. See Payments.

Mobile app

The app can’t reach the API

Android emulator: localhost is the emulator itself. In development the app already calls http://10.0.2.2:8000/api, so make sure the API is running on port 8000.
iOS simulator: the app calls http://localhost:8000/api.
A real device: neither address works. Change getApiBaseUrl in apps/mobile/src/config/environment.ts to your computer’s LAN IP address.

`pnpm ios` or `pnpm dev:mobile` fails straight away

The mobile app is outside the pnpm workspace and has its own node_modules. Install it first with pnpm mobile:install (or cd apps/mobile && npm install), then run the command again.

Pod install or iOS build fails

Install the pinned CocoaPods through Bundler (bundle install, then cd ios && bundle exec pod install). Two problems come up often:

Unicode Normalization not appropriate for ASCII-8BIT — your shell has no UTF-8 locale. Run export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 first.
CDN: trunk URL couldn't be downloaded … HTTP2 framing layer — a network hiccup on the CocoaPods CDN. Run pod install --repo-update again; if one spec keeps failing, download it with curl into ~/.cocoapods/repos/trunk/Specs/… and run pod install without --repo-update.