Errors
The library throws one error class, OcflError, for anything you might handle. This page lists every value of its code, what causes it, and what to do. Coming from 0.4, which threw plain Errors? See Migrating from 0.4.
Catching an OcflError
Section titled “Catching an OcflError”Test code. The message names the object or path involved and is useful in logs, but it isn’t part of the contract and may change. New codes can arrive in a minor release, so a switch on code keeps a default branch.
Two fields are set only some of the time:
ocflCodeis the code the OCFL specification gives the rule that was broken, such asE060, when the fault has one. OnlyINVALID_OBJECTandINVALID_STORAGE_ROOTcarry one.lockedAtis when another writer took the object’s lock. OnlyUPDATE_IN_PROGRESSsets it, and it is absent if the lock couldn’t be read or was released in the meantime.
cause, when set, is the error underneath. RECOVERY_NEEDED always sets it.
import { OcflError, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');const id = 'item-1';
try { const object = await root.open(id); await object.update({ message: 'Add notes', user: { name: 'Alice' } }, async (draft) => { await draft.write('notes.txt', 'Field notes'); });} catch (error) { if (!(error instanceof OcflError)) { throw error; } switch (error.code) { case 'OBJECT_NOT_FOUND': console.log(`There is no object ${id}`); break; case 'UPDATE_IN_PROGRESS': console.log(`Another writer has held the lock since ${error.lockedAt?.toISOString() ?? 'an unknown time'}`); break; case 'INVALID_OBJECT': console.log(`The object is damaged (${error.ocflCode ?? 'no OCFL code'}): ${error.message}`); break; default: throw error; }}objects() doesn’t throw for an object it can’t open. It yields { error, objectRoot, id? } in that object’s place and carries on listing. error has the code INVALID_OBJECT. objectRoot is the damaged object root’s path from the storage root, and id is the id its root inventory names, absent when the inventory can’t be read, isn’t JSON or names none:
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
for await (const entry of root.objects()) { if ('error' in entry) { const { objectRoot, id, error } = entry; console.warn(`${objectRoot}${id ? ` (${id})` : ''}: ${error.ocflCode ?? error.code}`); continue; } console.log(entry.object.id, entry.object.head.number);}What isn’t an OcflError
Section titled “What isn’t an OcflError”- A
TypeErrormeans the call itself was wrong: a required argument is missing or empty, an argument has the wrong type, an options object has an extra key, a version’screatedAtis earlier than the head version’s, orcreateStorageRootwas given a storage layout or parameter it doesn’t have or refuses. The API reference lists each method’s. - A
RangeErrormeans a byte range given toOcflFile.stream()has an end that isn’t a whole number from 0, astartafter itsend, or astartafter the file’s last byte. - A plain
Errormeans a draft was used after its update finished, or an update ended with draft operations still running. Await every operation. - An aborted
signalrejectscheckFixity,createorupdatewith the signal’sreason, whatever that is: anAbortSignal.timeout()gives aTimeoutErrorDOMException, andcontroller.abort()with no reason anAbortErrorone. - File system errors, such as
ENOSPCorEACCES, pass through untouched.
None of these is retryable as it stands. Fix the call, or the file system.
Storage roots
Section titled “Storage roots”DIRECTORY_NOT_EMPTY
Section titled “DIRECTORY_NOT_EMPTY”Cause: createStorageRoot was given a directory that already has something in it. Rarely, create throws it too, when something appeared in the new object’s directory while its first version was being built.
What to do: create the storage root in an empty or missing directory. To use a storage root that already exists, call openStorageRoot.
STORAGE_ROOT_NOT_FOUND
Section titled “STORAGE_ROOT_NOT_FOUND”Cause: openStorageRoot was given a path that doesn’t exist, or an empty directory. There is no storage root there.
What to do: to make one, call createStorageRoot with the same path. To open a storage root, or create it if it isn’t there, catch this code and nothing else:
import { createStorageRoot, OcflError, openStorageRoot, type StorageRoot } from '@ocfl/ocfl-fs';
async function openOrCreate(path: string): Promise<StorageRoot> { try { return await openStorageRoot(path); } catch (error) { if (!(error instanceof OcflError && error.code === 'STORAGE_ROOT_NOT_FOUND')) { throw error; } return createStorageRoot(path, { layout: { extensionName: '0004-hashed-n-tuple-storage-layout' } }); }}
const root = await openOrCreate('/srv/ocfl');console.log(root.layout.extensionName);INVALID_STORAGE_ROOT
Section titled “INVALID_STORAGE_ROOT”Cause: openStorageRoot found no storage root it can read: the path is a file, is below a file, or is a directory with something in it, and its 0=ocfl_1.x declaration is missing or wrong (ocflCode E069 or E080), ocfl_layout.json is missing, or doesn’t name a storage layout (E070), or the storage layout’s config.json isn’t a JSON object, is for another storage layout, or has parameters the storage layout refuses.
What to do: check the path is a storage root. If it is, fix the declaration, ocfl_layout.json or config.json; the message names the file.
A storage root with no ocfl_layout.json can’t be opened: without it the library can’t tell where each object is, and it doesn’t guess. Add an ocfl_layout.json naming the storage layout the root’s objects are laid out by, such as {"extension": "0004-hashed-n-tuple-storage-layout"}, with that storage layout’s config.json under extensions/ if it doesn’t use the default parameters. The message lists the storage layouts the library has.
UNSUPPORTED_LAYOUT
Section titled “UNSUPPORTED_LAYOUT”Cause: openStorageRoot found a storage root whose ocfl_layout.json names a storage layout the library doesn’t have. The library has four: 0002-flat-direct-storage-layout, 0003-hash-and-id-n-tuple-storage-layout, 0004-hashed-n-tuple-storage-layout and the local 000N-path-direct-storage-layout.
What to do: the message names the storage layout the root declares and lists the ones the library has. To open the storage root with this library, ask for the storage layout to be added; until then, use another tool for it. A caller can’t plug in a storage layout of its own.
Finding objects
Section titled “Finding objects”OBJECT_NOT_FOUND
Section titled “OBJECT_NOT_FOUND”Cause: there is no object with this id: nothing is in the directory the storage layout maps it to. open also throws it for an object another writer is creating and hasn’t committed.
What to do: catch it instead of checking whether the object exists first; a check can be out of date by the time you act on it. To make the object, call create.
OBJECT_EXISTS
Section titled “OBJECT_EXISTS”Cause: create found an object already there, or another writer created it first.
What to do: open the existing object, and update it if you meant to change it.
ID_INCOMPATIBLE_WITH_LAYOUT
Section titled “ID_INCOMPATIBLE_WITH_LAYOUT”Cause: the storage root’s storage layout can’t place an object with this id. Either the storage layout can’t map the id, or it maps it somewhere an object can’t go: the storage root itself, outside it, the extensions directory, or a path too long for the file system (with the path-direct storage layout, an id of many long segments). Each storage layout has its own rules. For example, 0002-flat-direct-storage-layout refuses an id with a / in it, ., .., extensions, or an id longer than 255 bytes, and the path-direct storage layout refuses an id with . or .. segments, or one that ends with or contains its suffix.
create and remove also throw it when the object’s lock in the workspace would be too long for the file system, even if its directory isn’t, so such an object can be opened but not changed.
The id is at fault, not what is in the storage root. Apart from a lock path that is too long, no object can have this id in this storage root, so a reader can treat it as not found.
What to do: choose another id, or a storage layout that suits your ids.
OBJECT_ROOT_CONFLICT
Section titled “OBJECT_ROOT_CONFLICT”Cause: the storage layout places the id, but the directory it maps to holds the wrong thing. open and remove throw it when that directory holds an object with a different id, or has no object declaration but holds other files, is a file, or is below one. create throws it when the directory isn’t empty, is a file or is below one, or is inside another object. unfinishedWrite throws it when the object’s lock in the workspace belongs to a writer of a different id.
The storage root is in a state a person needs to look at, often from an object moved or copied by hand, or written by a tool with another storage layout. A server should log it, not treat it as not found.
What to do: don’t retry. Look at what is in the directory before doing anything; the message names it.
INVALID_OBJECT
Section titled “INVALID_OBJECT”Cause: what the library read where the object should be isn’t an object it can safely use. The inventory is missing, isn’t JSON, is inconsistent, or names paths that would lead outside the object; the sidecar digest is missing or doesn’t match; the object declaration is missing or wrong, or declares a later OCFL version than the storage root’s; or the object is inside another object. Reading a file throws it if its stored file is missing or isn’t a regular file, such as a directory, with the file system error, if any, as its cause. ocflCode names the OCFL rule, for example E003 (no object declaration), E033 (inventory isn’t JSON), E060 (sidecar digest doesn’t match) or E081 (a 1.1 object in a 1.0 storage root).
open, update, remove, recovering an unfinished write, objects(), and an OcflFile’s size(), stream(), text() and bytes() can all give it. update throws it if the declaration has been damaged since the object was opened, or removed while anything remains in the object root. Rarely, create throws it when an invalid declaration appeared in the new object’s directory while its first version was being built.
These are checks the library makes before it uses an inventory’s values as file paths. They are not validation: an object that opens can still break OCFL rules the library never looks at. To check an object against the specification, use an OCFL validator. See It doesn’t validate for what the library checks and what it doesn’t.
What to do: don’t retry; the object is damaged and needs a person to look at it. Repair it with the tool that made it, or from a backup. If you no longer want it, see Removing a damaged object.
MUTABLE_HEAD_ACTIVE
Section titled “MUTABLE_HEAD_ACTIVE”Cause: update found an active mutable head (extensions/0005-mutable-head) in the object. The library doesn’t support that extension.
What to do: commit or discard the mutable head with the tool that made it, then update the object.
VERSION_LIMIT_REACHED
Section titled “VERSION_LIMIT_REACHED”Cause: update can’t name the next version. The object’s version names are zero-padded, and OCFL requires a padded name to start with a zero, so v01 to v09 allows nine versions and v001 to v099 allows 99. Objects this library creates aren’t padded and never reach a limit.
What to do: the library can’t add a version to this object. See When the object is full.
Writers and locks
Section titled “Writers and locks”UPDATE_IN_PROGRESS
Section titled “UPDATE_IN_PROGRESS”Cause: create, update or remove found the object’s lock taken: another writer is creating, updating or removing it, or died doing so. The library refuses straight away, never waits, and never removes a lock because of its age. lockedAt says when the lock was taken.
What to do: wait and try again. If you know the writer is dead, recover the object’s unfinished write, from root.unfinishedWrite(id), and then try again. Only recover it when its writer is no longer alive: recovering destroys a live writer’s update. Recovering a write also throws UPDATE_IN_PROGRESS, changing nothing, if another writer took the lock after you got the write. See UPDATE_IN_PROGRESS in Concurrent writers and recovery.
OBJECT_OUT_OF_DATE
Section titled “OBJECT_OUT_OF_DATE”Cause: update found that a later version was committed after you opened the object, or the object was removed, whether or not it was created again. It is checked before your change runs and again just before commit. Nothing is committed.
What to do: open the object again and repeat the update against the new head. If the object was removed, opening it throws OBJECT_NOT_FOUND. See OBJECT_OUT_OF_DATE in Concurrent writers and recovery for a retry loop.
RECOVERY_NEEDED
Section titled “RECOVERY_NEEDED”Cause: a write failed at a point where the library can’t tell, or can’t put right, what happened. That is one of:
createorupdatefailed after the commit point, or failed replacing the root inventory in a way that may have replaced it. The update may have been committed.- A failed update couldn’t remove everything it had made.
removefailed part of the way through, so the object may be partly deleted.removedeleted the object but couldn’t release its lock.create,updateorremovewas refused and couldn’t release the lock it had taken. Apart from the lock, nothing is changed.- An earlier writer left an unfinished version in the workspace. This is thrown before your change runs.
cause is the underlying failure. The object stays locked, so later writes get UPDATE_IN_PROGRESS until it is recovered, and it is among the storage root’s unfinished writes. It can still be read.
What to do: don’t simply repeat the write. Once no writer of the object is alive, recover its unfinished write: (await root.unfinishedWrite(id))?.recover(). After a create or update, open the object again and look at the head to see whether your version was committed; retry only if it wasn’t. After a remove that had begun deleting, recovering finishes removing the object. After a refused write, recovering only releases the lock: nothing was changed, so repeat the write. See RECOVERY_NEEDED in Concurrent writers and recovery.
CROSS_FILESYSTEM_MOVE
Section titled “CROSS_FILESYSTEM_MOVE”Cause: the new version couldn’t be moved from the workspace (extensions/ocfl-js-workspace in the storage root) into the object, because the two are on different file systems. Nothing is committed.
What to do: keep the whole storage root on one file system. A mount point inside the storage root splits it.
UNSUPPORTED_FILESYSTEM
Section titled “UNSUPPORTED_FILESYSTEM”Cause: create, update or remove couldn’t take the object’s lock, because the storage root’s file system refused to hard-link it. Usually the file system has no hard links, as FAT, exFAT, most FUSE object-store mounts and SMB shares without POSIX extensions don’t. cause is the underlying error; an EPERM can also come from an immutable or append-only directory. Nothing is changed and no lock is left.
What to do: move the storage root to a file system with hard links, such as a local Linux file system or NFS. Reading works where it is. If the file system has hard links, check the attributes of the workspace (extensions/ocfl-js-workspace) with lsattr.
Drafts
Section titled “Drafts”These come from draft operations inside the function you pass to create or update. Unless you catch them there, the whole update is discarded, the object is left as it was, and the error is thrown from create or update. Updating objects describes each operation.
FILE_NOT_FOUND
Section titled “FILE_NOT_FOUND”Cause: copy, rename or remove was given a path with no file or directory in the draft, or reinstate a path with nothing at it in that version, or a version that doesn’t exist.
What to do: check the path against object.head.files, or against the version’s files for reinstate.
FILE_EXISTS
Section titled “FILE_EXISTS”Cause: the operation would put a file where a directory is, or a file below another file. copy and rename also throw it for a directory onto a target that already has files, without { merge: true }.
What to do: remove what is in the way first, or pass { merge: true } to put the directory’s files in among the target’s.
INVALID_LOGICAL_PATH
Section titled “INVALID_LOGICAL_PATH”Cause: a logical path is empty, absolute, or has a .. segment (a backslash counts as a separator); a copy or rename target is inside its source; or an import target is empty or names the top of the object, such as ..
What to do: use a relative path without ... To import a directory’s contents at the top of the object, leave out the target.
SOURCE_CHANGED
Section titled “SOURCE_CHANGED”Cause: a file changed while import was copying it in: the copy’s digest doesn’t match the source.
What to do: retry once nothing is writing to the source.
UNSUPPORTED_FILE_TYPE
Section titled “UNSUPPORTED_FILE_TYPE”Cause: import found a symbolic link, socket, device or anything else that isn’t a regular file or directory.
What to do: import the files the link points to, or, for a link below the source, leave it out with import’s filter option.
When the library offers no way forward
Section titled “When the library offers no way forward”When the object is full
Section titled “When the object is full”An object with zero-padded version names that has reached VERSION_LIMIT_REACHED can’t take another version from this library. Either:
- update it with the tool that made it, if that tool can renumber or otherwise carry on; or
- copy its head into a new object, which has no padding and no limit. The new object needs a new id while the old one exists, and it starts again at version 1, so the earlier versions stay only in the old object.
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');const full = await root.open('item-1');
await root.create('item-1-continued', { message: `Copy of the head of ${full.id}`, user: { name: 'Alice' } }, async (draft) => { for (const [path, file] of full.head.files) { await draft.write(path, await file.stream()); }});Removing a damaged object
Section titled “Removing a damaged object”remove refuses an object it can’t read with INVALID_OBJECT, because it can’t confirm the directory holds the object you named. Nothing is deleted.
If you are sure you want it gone:
- Make sure no writer of the object is alive.
- Delete the damaged object root by hand: the directory
objects()gives asobjectRoot, inside the storage root. It is where the storage layout places the id. - If the workspace (
extensions/ocfl-js-workspacein the storage root) has a directory at the same path, delete that too. - Remove any parent directories that leaves empty, up to the storage root.