A useful place to start.

Handle errors while preserving existing records, keys and metadata.

Read the error code

try {
  await BsonLite.connect();
} catch (error) {
  console.error(error.code, error.message);
  process.exitCode = 1;
}

Code	What to check
BSONLITE_NOT_STARTED	Await connect before collection or ping.
BSONLITE_INVALID_OPTIONS	Use documented options with valid types; open needs an object.
BSONLITE_CONFIG_CONFLICT	Shared connection already has different settings. Use a separate open handle and directory if intended.
BSONLITE_PERMISSIONS	Use a private writable NTFS location with account access controls.
BSONLITE_PRIVATE_LOCATION	Keep the managed engine/vault outside the project.
BSONLITE_NATIVE_MIGRATION_REQUIRED	Preserve the existing store; follow the supported migration path.
BSONLITE_BACKUP_AUTH_FAILED	Wrong password or a changed/truncated backup; preserve original copies.

Stale locks after a crash

Close all applications using the store and wait at least 60 seconds after startup/crash before explicit stale-lock recovery. The recovery helper checks project and private-store ownership plus recorded engine processes.

// Only after every application using this store has stopped:
const result = BsonLite.recover({ directory: './Database' });
console.log(result.removedLocks);

recover is synchronous. It refuses living or ambiguous owners and does not kill processes or reset data. If ownership cannot be proven, investigate rather than deleting lock or key files.

A startup error is not a reset request

Keep your data

Do not delete Database, change store IDs, remove the vault or modify native encryption metadata to make startup proceed. Save the exact error, keep matching backups and inspect the supported profile.

The default embedded SDK does not require EFS or BitLocker. An earlier-format encryption error can indicate an older store or explicit legacy policy. Check version and migration guidance before changing any settings. Contact info@bsonlite.com with the SDK version and a redacted error message; do not send secrets or private database records.

Documentation for BsonLite 0.6.0-rc.1. View SDK source · Download the validated SDK