paperclipai/paperclip · error · Error

PAPERCLIP_ADAPTERS_FILE could not be read at "${filePath}":

Error message

PAPERCLIP_ADAPTERS_FILE could not be read at "${filePath}": ${(err as Error).message}

What it means

Env-bootstrap failure in parseAdapterRegistryEnv: PAPERCLIP_ADAPTERS_FILE points at a file path, but fs.readFileSync failed (missing file, permissions, etc.). Startup aborts with the underlying OS error message so the operator can fix the path or file mode.

Source

Thrown at server/src/services/adapter-registry-bootstrap.ts:41

/**
 * Parse the declarative registry from env. Returns null when unconfigured
 * (built-in defaults; local/OSS unchanged). Throws on malformed/invalid input.
 */
export function parseAdapterRegistryEnv(
  env: AdapterRegistryEnv = process.env,
): AdapterRegistryEntryParsed[] | null {
  const inline = env.PAPERCLIP_ADAPTERS?.trim();
  const filePath = env.PAPERCLIP_ADAPTERS_FILE?.trim();
  if (!inline && !filePath) return null;

  let rawText: string;
  if (inline) {
    rawText = inline;
  } else {
    try {
      rawText = fs.readFileSync(filePath as string, "utf-8");
    } catch (err) {
      throw new Error(
        `PAPERCLIP_ADAPTERS_FILE could not be read at "${filePath}": ${(err as Error).message}`,
      );
    }
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(rawText);
  } catch (err) {
    throw new Error(`PAPERCLIP_ADAPTERS must be valid JSON: ${(err as Error).message}`);
  }

  const result = adapterRegistrySchema.safeParse(parsed);
  if (!result.success) {
    throw new Error(
      `PAPERCLIP_ADAPTERS failed validation: ${result.error.issues
        .map((i) => `${i.path.join(".")}: ${i.message}`)
        .join("; ")}`,

View on GitHub (pinned to 120ae5428f)

Solutions

1. Check that the file at PAPERCLIP_ADAPTERS_FILE exists and is readable; fix the reported read error.

When it happens

Trigger: Thrown at server/src/services/adapter-registry-bootstrap.ts:41 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/d2247ebadd19ee62. Report an issue: GitHub.