Troubleshooting

If something isn’t working, it’s probably one of these.

“Cannot read or find Context file’AppContext.js’”#

The migration CLI resolves a context by file name. Your context must live in a file matching the name you pass:

# file must be named AppContext.js
masterrecord enable-migrations AppContext

“The ‘path’ argument must be of type string”#

You passed an inline config object to env() on a version older than 1.3.0. Upgrade, or use the environment-file form.

SQLite tries to create /db at the filesystem root#

Your connection starts with a leading slash. Use a relative path so it resolves under the project root:

{ "AppContext": { "type": "better-sqlite3", "connection": "db/" } }

“near ‘)’: syntax error” when migrating#

Your entity defined fields as constructor object-literals instead of builder methods, so no columns were registered. Define fields as methods:

id(db)   { db.integer().primary().auto(); }   // ✅
title(db){ db.string(); }                       // ✅

Configuration missing settings for context#

Your env JSON isn’t keyed by the context class name. Wrap settings under the context key:

{ "AppContext": { "type": "postgres", "host": "..." } }

“ERR_INVALID_MODULE_SPECIFIER” on Linux after migrating on Windows#

A migration snapshot generated on Windows before 1.3.1 stored its contextLocation with backslashes (e.g. "..\\..\\AppContext.js"), which Linux treats as literal filename characters — so the CLI failed before running any migration. Upgrade to masterrecord@1.3.1: the CLI now normalizes path separators when reading and writing snapshots, so already-committed snapshots work without regeneration.

“Bulk insert failed, falling back to individual inserts” in your logs#

On versions before 1.3.1, saving a batch where rows populated different column sets (some rows leave optional fields unset) produced a malformed multi-row INSERT on MySQL/Postgres and silently fell back to slow per-row inserts. Upgrade to masterrecord@1.3.1 — heterogeneous batches now emit one statement per column signature and stay on the fast path, and omitted columns keep their database DEFAULT.

Still stuck?#