Errors

Every failure that's the library's job to surface lands as an FsSafeError with a closed code union you can branch on. Catch by code, not by message text — messages may change, codes will not.

Path and archive-entry details embedded in diagnostics escape control characters as \\uXXXX sequences. This keeps attacker-controlled names on one log line; the escaped message is for diagnosis, not for reconstructing the original path.

import { FsSafeError, type FsSafeErrorCode } from "@openclaw/fs-safe";

#Shape

class FsSafeError extends Error {
  readonly name: "FsSafeError";
  readonly code: FsSafeErrorCode;
  readonly category: "policy" | "operational";
  readonly details?: Readonly<Record<string, unknown>>;

  constructor(
    code: FsSafeErrorCode,
    message: string,
    options?: { cause?: unknown; details?: Readonly<Record<string, unknown>> },
  );
}

cause is available through the standard Error cause property when the failure was triggered by a NodeJS.ErrnoException (e.g. a wrapped EACCES). Inspect it for the original code / errno / syscall if you need finer-grained reporting.

details is an operation-specific receipt, not an alternate error code. For example, publishFileExclusive() uses it to report the failing phase, created target identity, cleanup decision, and failed directory-sync outcome. Narrow by code and a documented details field before consuming it; do not assume all FsSafeError instances carry the same keys.

replaceFileAtomic({ copyFallbackRestore: "restore-original" }) reports a failed copy fallback with the exported ReplaceFileAtomicRestoreFailureDetails shape:

type ReplaceFileAtomicRestoreFailureDetails = {
  cleanup: "restored" | "restore-failed";
};

Both outcomes use code: "helper-failed". "restored" means the original snapshot was written back and fsynced through the pinned destination handle. "restore-failed" means both the replacement and recovery failed; cause is an AggregateError containing both failures. A snapshot that exceeds maxRestoreBytes fails earlier with too-large and does not overwrite the destination.

category separates caller-policy failures from operational failures:

• "policy" — unsafe input or target state rejected by a safety policy, such as outside-workspace, symlink, hardlink, or too-large.
• "operational" — routine filesystem outcomes or environment/runtime failures, such as not-found, not-empty, not-removable, helper startup, platform support, timeout, or unverifiable permissions.

Routine absence or inability to remove a path does not by itself indicate a filesystem boundary violation. Branch on the specific code when the distinction between those operational outcomes matters.

The operational set is exactly helper-failed, helper-unavailable, not-empty, not-found, not-removable, permission-unverified, read-failed, timeout, and unsupported-platform. Every other current FsSafeErrorCode, including store-reentrant-update, is categorized as policy.

#Code union

type FsSafeErrorCode =
  | "already-exists"
  | "denied-path"
  | "device-path"
  | "hardlink"
  | "helper-failed"
  | "helper-unavailable"
  | "insecure-permissions"
  | "invalid-path"
  | "not-empty"
  | "not-file"
  | "not-found"
  | "not-owned"
  | "not-removable"
  | "outside-workspace"
  | "path-alias"
  | "path-mismatch"
  | "permission-unverified"
  | "read-failed"
  | "secret-exists"
  | "store-reentrant-update"
  | "symlink"
  | "timeout"
  | "too-large"
  | "unsupported-platform";

#Code reference

#Branching

import { FsSafeError } from "@openclaw/fs-safe";

try {
  await fs.write("../escape.txt", "x");
} catch (err) {
  if (!(err instanceof FsSafeError)) throw err;
  switch (err.code) {
    case "outside-workspace":
      return reply(400, "path escapes workspace");
    case "already-exists":
      return reply(409, "exists");
    case "too-large":
      return reply(413, "too large");
    case "not-found":
      return reply(404, "missing");
    case "symlink":
    case "device-path":
    case "hardlink":
    case "path-mismatch":
    case "path-alias":
      return reply(400, "unsafe path");
    default:
      throw err;
  }
}

The default above deliberately rethrows unknown codes, so it remains safe as the union grows. If you want the compiler to flag every newly added code, end an exhaustive switch with a never assertion instead of a general default.

#Distinguishing from NodeJS.ErrnoException

Some failures bubble up as native Node errors (e.g. EACCES, EPERM, EISDIR, EBUSY) when they don't map cleanly to a library code. Inspect both:

import { FsSafeError } from "@openclaw/fs-safe";

try {
  await op();
} catch (err) {
  if (err instanceof FsSafeError) {
    handleFsSafe(err);
    return;
  }
  const code = (err as NodeJS.ErrnoException).code;
  if (code === "EACCES" || code === "EPERM") {
    handleAccess();
    return;
  }
  throw err;
}

A common pattern is to wrap your domain code in a single try/catch that maps both shapes to your application's typed error format.

On Windows, access-denied failures from native root/open filesystem operations use EPERM to match Node/libuv and the JavaScript fallback. Security-descriptor inspection has its own failure surface. Older fs-safe versions could report EACCES for the same root/open condition, so consumers spanning versions should accept both codes.

#Specialty errors

A handful of helpers throw their own typed errors instead of FsSafeError:

• JsonFileReadError — thrown by readJson. Carries cause so you can distinguish missing (ENOENT) from invalid (SyntaxError).
• ArchiveLimitError — thrown by extractArchive when an archive size, entry count, path depth, metadata, or extracted-byte budget is exceeded. The code field uses the string values exposed by ARCHIVE_LIMIT_ERROR_CODE (for example archive-entry-path-components-exceeds-limit).
• ArchiveSecurityError — thrown by extraction when entry policy or destination safety fails. Entry codes are entry-path, entry-link, and entry-filtered; destination codes cover non-directory, symlink, and symlink-traversal failures.

These are exported from their respective subpaths.

#Why FsSafeError?

Two reasons it isn't a richer hierarchy of subclasses:

1. Switch on code, don't instanceof a tree. code is a closed string union the TypeScript compiler can exhaust-check. Subclasses make instanceof ladders that drift over time.
2. One catch handler. Library callers often want a single "is this an fs-safe failure?" gate before deciding what to do — instanceof FsSafeError plus a switch is the cleanest expression of that.

#See also

• root() — every method documents the codes it can throw.
• Reading — read-path codes.
• Writing — write-path codes.
• Archive extraction — ArchiveLimitError and ArchiveSecurityError.