Troubleshooting

The problems people actually hit, and what each one means.

The banner names one of three things: the API is not running, it cannot reach MongoDB, or the process is an older build than the dashboard expects (usually after a git pull without restarting). GET /api/health returns db, version and a features list; the fix is almost always to restart the API.

bash

pnpm --filter api run dev

The storefront logs "[api] 404 — … restart apps/api"

Same cause. The storefront keeps rendering with bundled defaults and logs one warning per route per minute; restart the API and the warning stops.

The API exits on boot with "credentials are not defined"

Only MONGO_URI and JWT_SECRET are required. If ImageKit or Cloudinary complain at boot, you are on an old build — current config/*.ts files degrade instead of throwing. Update, then check that .env is at the repo root, not inside apps/api.

ImageKit returns 403 "account cannot be authenticated"

The private key is wrong or has a stray character. Valid keys start with private_ and are 36 characters. Test it directly:

bash

curl -u "$IMAGEKIT_PRIVATE_KEY:" https://api.imagekit.io/v1/files?limit=1

Freshly seeded data does not show on the storefront

Next's Data Cache survives dev-server restarts. src/lib/api.ts sets revalidate: 0 in development to avoid this; if you see stale data in a production build, redeploy or call the revalidation path. Deleting .next/ locally also clears it.

Navigating lands part-way down the page

<html> must carry data-scroll-behavior="smooth" because globals.css sets smooth scrolling. Next 16 no longer overrides it during navigation without that attribute. It is in every root layout — do not remove it.

Build fails with a "Pages Router" error in a client component

A client component imported a *value* from a module that reaches next/headers. Import only types from server modules, or move the shared constants into a pure module — the admin's order labels live in data/order-status.ts for exactly this reason. tsc will not catch it; only pnpm run build does.

`pnpm install` reports ignored build scripts

pnpm 11 refuses to run native postinstall scripts that are not allow-listed. Add the package under allowBuilds in pnpm-workspace.yaml — the package.json pnpm field is no longer read.

`ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL` on lint in the Next apps

The Next apps are pinned to ESLint 9: eslint-config-next@16 depends on plugins whose peer ranges end at ^9. Do not align them with the API's ESLint 10.

The dashboard refuses a valid login

Only staff roles may sign in there. A customer account — including one that signed in with Google — is refused by design. Grant a role from Users & Roles on an admin session, or run create:admin.

COD orders fail validation

The address needs postalCode, not zipCode. The storefront sends the right shape; if you are calling the API directly, match the Order model.

A deleted image still loads

ImageKit's CDN keeps serving a deleted URL for a while. Verify deletions with imagekit.assets.list, not by fetching the URL.