paperclipai/paperclip · error · Error

PAPERCLIP_ADAPTERS must be valid JSON

Error message

PAPERCLIP_ADAPTERS must be valid JSON: ${(err as Error).message}

What it means

Env-bootstrap failure in parseAdapterRegistryEnv: the raw text from PAPERCLIP_ADAPTERS (or the file) is not valid JSON. JSON.parse's message is embedded so the operator can find the syntax error before the registry schema is even applied.

Solutions

1. Fix PAPERCLIP_ADAPTERS to contain valid JSON.

When it happens

Trigger: Thrown at server/src/services/adapter-registry-bootstrap.ts:51 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/2967eb018b39ceda. Report an issue: GitHub.

Appendix: source

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

  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("; ")}`,
    );
  }
  return result.data;
}

/**
 * Reconcile availability: every known server adapter NOT enabled in the declared
 * registry is disabled; declared+enabled ones are enabled. Throws if a declared
 * adapterType has no installed adapter (cannot offer a harness with no
 * implementation). No-op when `registry` is null.

View on GitHub (pinned to 120ae5428f)