Skip to content

Local Development Troubleshooting

npm install fails with a lockfile/EINTEGRITY error

package-lock.json drifted from package.json (e.g. a manual npm install <pkg> in one workspace without committing the resulting lockfile change). From docs/DEPLOYMENT.md's own troubleshooting table: 

npm install
git diff package-lock.json    # review, then commit

npm run check:portal-styles-drift fails

Someone edited a generated apps/*/public/*/shared.css by hand, or edited packages/ui/src/portal-shared.css without running the sync: 

npm run sync:portal-styles
git diff --stat                # review what changed
git add apps/corporate-web/public/customer-portal/shared.css apps/software-web/public/freelancer-portal/shared.css
Never hand-edit the two generated copies directly.

npm run build fails only for one app

npm run build:<app>    # isolate it
Check that app's own tsconfig.json/worker/tsconfig.json (Corporate/Software/Admin) - a type error in one app's worker/ code fails only that app's build, not the others.

Vite dev server port conflict

Vite auto-increments past a taken port and logs the actual one - check the terminal output rather than assuming the default 5173.

wrangler dev (API or an app's own Worker) can't find D1/R2 locally

Confirm you're running it from the right directory (workers/api, or apps/corporate-web / apps/software-web / apps/admin-web for their own Worker) - Wrangler resolves bindings from the wrangler.jsonc in the current directory. No wrangler login/credentials are needed for local (--local) D1/R2 emulation.

Local D1 migrations don't reflect a change I just made

cd workers/api
npm run db:local
Re-applies any migration files not yet applied to the local emulator - never touches production. See Cloudflare → D1.

Tests pass locally but fail in CI (or vice versa)

CI runs on ubuntu-latest, Node 22 - a Windows-specific path/line-ending assumption in a test is the most common cause of a local-only pass. Run npm test fresh after npm ci (not npm install) to rule out a stale node_modules state matching CI more closely.