Error Handling & Recovery

file-json-db is designed to be resilient. A corrupted part file should not take down the whole collection or the process. This page explains what happens when things go wrong and how you can recover.

errorLevel option

When you create a collection you can choose how corrupted parts are treated:

Value	Behaviour
`'debug'` (default)	Copy the bad part once into a `crash/` subdirectory, record it in `index.corruptedParts`, emit an `error` event, and skip the part from then on.
`'ignore'`	Silently skip the part. No copy is made and no error is emitted for the parse failure.

const logs = db.collection({
  name: 'logs',
  errorLevel: 'ignore'   // never surface parse errors
});

What “corrupted” means

A part is considered corrupted when JSON.parse throws while reading it (truncated file, invalid JSON, unexpected end of input, etc.). Empty or whitespace-only files are treated as empty arrays, not as errors.

The crash/ directory

In debug mode the library copies a failing part exactly once:

data/users/
├── index.json
├── part-0001.json
├── part-0002.json
└── crash/
    └── part-0003.json   ← the bad file, preserved for inspection

The original file is left in place (so you can still examine it) but is never parsed again because its key is recorded in corruptedParts.

Listening for errors

db.on('error', (err) => {
  console.error('[file-json-db]', err.message);
  // send to your monitoring system
});

users.on('error', (err) => {
  // collection-specific handling
});

Recovering a corrupted part

Inspect the copy under crash/ and the original part file.
Fix the JSON manually if possible, or decide to discard the data.
Remove the entry for that part from index.corruptedParts (or delete index.json and let the library rebuild).
Call collection.rebuildIndexes().

// After you have fixed or removed the bad part file:
users.rebuildIndexes();
// The collection will re-scan all remaining parts and rebuild idIndex + secondary indexes.

Atomic-write failures

Writes use a temp-file + rename strategy with retries. If all retries fail, an error is emitted and the original file is left intact. The temporary file is cleaned up when possible.

Best practices

Always attach an error listener on the database object in long-running apps.
Keep periodic backups so you can restore a whole collection if needed.
Prefer smaller maxPartSize values if you want finer isolation of damage.
Never edit part files by hand while the process is running.