Skip to content

fix(core): actionable error for stale better-sqlite3 native binary#582

Merged
ascorbic merged 2 commits intoemdash-cms:mainfrom
all3f0r1:fix/better-sqlite3-node-version-error-562
Apr 15, 2026
Merged

fix(core): actionable error for stale better-sqlite3 native binary#582
ascorbic merged 2 commits intoemdash-cms:mainfrom
all3f0r1:fix/better-sqlite3-node-version-error-562

Conversation

@all3f0r1
Copy link
Copy Markdown
Contributor

What does this PR do?

When Node.js is upgraded (or node_modules was built with a different Node version), better-sqlite3 fails to load with a NODE_MODULE_VERSION mismatch. Today, createDatabase catches this and surfaces a generic Failed to create database — the real cause is only visible if the user digs into the cause.

This PR detects the NODE_MODULE_VERSION string in the underlying error and throws an EmDashDatabaseError whose message tells the user exactly what to do: rebuild the native module with pnpm rebuild better-sqlite3 (or reinstall deps).

The helper is exported and covered by unit tests.

Closes #562

Type of change

  • Bug fix
  • Feature (requires maintainer-approved Discussion)
  • Refactor (no behavior change)
  • Translation
  • Documentation
  • Performance improvement
  • Tests
  • Chore (dependencies, CI, tooling)

Checklist

  • I have read CONTRIBUTING.md
  • pnpm typecheck passes
  • pnpm lint passes
  • pnpm test passes (or targeted tests for my change)
  • pnpm format has been run
  • I have added/updated tests for my changes (if applicable)
  • User-visible strings in the admin UI are wrapped for translation and pnpm locale:extract has been run (if applicable)
  • I have added a changeset (if this PR changes a published package)
  • New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/...

AI-generated code disclosure

  • This PR includes AI-generated code

Screenshots / test output

 ✓ tests/database/connection.test.ts (13 tests) 84ms
 Test Files  1 passed (1)
      Tests  13 passed (13)

… stale

When Node.js is upgraded without rebuilding native deps, better-sqlite3 throws
a NODE_MODULE_VERSION mismatch that createDatabase surfaces only as a generic
"Failed to create database". Detect this specific case and tell the user to
rebuild or reinstall the native module.

Closes emdash-cms#562

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Apr 15, 2026

🦋 Changeset detected

Latest commit: 23d54cc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages
Name Type
emdash Patch
@emdash-cms/cloudflare Patch
@emdash-cms/admin Patch
@emdash-cms/auth Patch
@emdash-cms/blocks Patch
@emdash-cms/gutenberg-to-portable-text Patch
@emdash-cms/x402 Patch
create-emdash Patch
@emdash-cms/plugin-embeds Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Apr 15, 2026

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@582

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@582

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@582

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@582

emdash

npm i https://pkg.pr.new/emdash@582

create-emdash

npm i https://pkg.pr.new/create-emdash@582

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@582

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@582

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@582

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@582

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@582

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@582

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@582

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@582

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@582

commit: 23d54cc

Copy link
Copy Markdown
Collaborator

@ascorbic ascorbic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. Good catch

@ascorbic ascorbic enabled auto-merge (squash) April 15, 2026 20:41
@ascorbic ascorbic merged commit 04e6cca into emdash-cms:main Apr 15, 2026
26 checks passed
@emdashbot emdashbot bot mentioned this pull request Apr 15, 2026
@all3f0r1 all3f0r1 deleted the fix/better-sqlite3-node-version-error-562 branch April 15, 2026 22:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Failed to create database when running pnpm run bootstrap/seed due to NODE_MODULE_VERSION mismatch (better-sqlite3)

2 participants