db:migrate fails with 'Could not locate the bindings file' (better-sqlite3) on fresh setup

[mattpocock]

Report

A student hit this running npm run db:migrate on a fresh clone, before any code changes:

npm run db:migrate

db:migrate
drizzle-kit migrate

No config path provided, using default 'drizzle.config.ts'
Reading config file '/workspace/drizzle.config.ts'
Error: Could not locate the bindings file. Tried:
 → /workspace/node_modules/better-sqlite3/build/better_sqlite3.node
...

Reported environment: npm v10.9.8, node v22.23.2, fresh git pull same day.

Note the path prefix /workspace/... — not a normal host clone path, so this may be happening inside Docker/a devcontainer/WSL rather than directly on the reporter's machine (unconfirmed).

Investigation so far

• Reproduced a clean install in a throwaway copy of this repo (rm -rf node_modules && npm install && npm run db:migrate) on Linux x64 — worked fine. better-sqlite3's install step (prebuild-install || node-gyp rebuild --release) successfully downloaded a prebuilt binary from GitHub releases; no compile fallback was needed.
• So this doesn't look like a broken lockfile or a repo-wide regression — it reproduces only in the reporter's environment.
• better-sqlite3's install script downloads a prebuilt native binary over the network, falling back to a local node-gyp compile (needs python3 + a C/C++ toolchain) if that fails. If both the network fetch and the compile fallback fail/are skipped, npm install can exit 0 while leaving no .node binding — surfacing later as this exact error at db:migrate time rather than at install time.

Likely causes (unconfirmed — need more info from reporter)

• Running inside a container/devcontainer/WSL where node_modules was built on a different OS/arch than the one actually executing db:migrate (classic bind-mount/cross-arch mismatch) — the /workspace path is the main clue pointing here.
• No outbound network access to GitHub releases during npm install (corporate proxy/VPN/offline sandbox), combined with missing local build tools (python3/make/g++, or Windows build tools) for the compile fallback.
• ignore-scripts set (globally or via npm config) so better-sqlite3's install script never runs at all.
• Antivirus / cloud-sync (e.g. OneDrive) stripping the compiled .node binary after install.

Next steps

Asked the reporter to confirm:

1. Whether they're running inside Docker/a devcontainer/WSL/cloud IDE, or /workspace is just their host folder name.
2. The OS/arch actually executing the commands (host vs. container, if applicable).
3. Output of:

   npm config get ignore-scripts
   rm -rf node_modules
   npm install --loglevel=verbose 2>&1 | grep -iE "better-sqlite3|prebuild|gyp"
   npm rebuild better-sqlite3 --verbose
   

Once we know the actual cause, this may turn into a README troubleshooting note for future students, since this is a plausible recurring pain point (native module install on varied student machines).

[mattpocock]

Verified this against real npm 12 (not just the advisory-only 11.x line) and it looks explained:

npm 12 (released ~Aug 2026) makes dependency install scripts opt-in via an allowScripts allowlist in package.json — unlisted scripts are blocked, not just warned about. npm 11.16–11.19 only print a warning and still run the script; only npm 12 actually withholds it.

Repro, using the real npm@12.0.2 binary (via npx npm@12.0.2) each time:

• Checked out 2ddb3fe~1 (the commit right before the allowScripts fix), clean install → npm warn install-scripts 6 packages had install scripts blocked because they are not covered by allowScripts, including better-sqlite3's. npm run db:migrate then fails with the exact "Could not locate the bindings file" error and candidate-path list from this issue.
• Same commit under npm@11.17.0 → only a warning, script still runs, binding builds fine. So npm 11.x cannot reproduce this failure at all.
• Current main (with the allowScripts block added in 2ddb3fe) under npm@12.0.2 → script runs, binding builds, db:migrate succeeds. The pinned versions in that block (better-sqlite3@12.11.1, the three esbuild versions, msw@2.15.0) still match what package-lock.json resolves today, so the allowlist isn't stale.

So the fix that's already on main genuinely resolves this failure mode — for anyone installing with npm 12.

The open question is the reporter's stated environment: npm v10.9.8, which predates the allowScripts feature entirely (shipped in 11.16) and would neither warn nor block. That version can't produce this exact error through this mechanism. So either:

• the npm install that actually ran used a different (newer) npm than what npm -v reported on their host — plausible given the /workspace path suggesting Docker/devcontainer, where the container's npm could easily be pinned separately from whatever's on the host — or
• something else is going on and this is a coincidence of an identical-looking error.

Worth asking the reporter to confirm the npm version at the exact point npm install was run (e.g. npm exec -- npm -v inside whatever shell actually ran the install), not just their host npm -v. If that comes back ≥12, this is already fixed on main and just needs them to re-pull; if it's genuinely 10.9.8, we're back to the original unexplained-environment theories.