paperclipai/paperclip · error · Error

Could not read managed install manifest at ${paths.manifestP

Error message

Could not read managed install manifest at ${paths.manifestPath}: ${String(error)}

What it means

Thrown by readInstallManifest()'s outer catch block for any error other than ENOENT while reading or validating install.json. This wraps the underlying error (which may be the 'unsupported manifest shape' error from the shape check, a JSON.parse SyntaxError, or a filesystem permission error) into a single message that includes the manifest path and the original error's string representation. This is the error callers actually see when the manifest is corrupt.

Source

Thrown at cli/src/install-store.ts:229

  }
  return path.join(paths.installsRoot, source, identifier);
}

export function readInstallManifest(paths = resolveInstallStorePaths()): InstallManifest | null {
  try {
    const value = JSON.parse(fs.readFileSync(paths.manifestPath, "utf8")) as InstallManifest;
    if (
      value.schemaVersion !== INSTALL_MANIFEST_VERSION ||
      (value.source !== "npm" && value.source !== "git") ||
      !Array.isArray(value.previous) ||
      typeof value.payloadPath !== "string"
    ) {
      throw new Error("unsupported manifest shape");
    }
    return value;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw new Error(`Could not read managed install manifest at ${paths.manifestPath}: ${String(error)}`);
  }
}

export function writeInstallManifestAtomic(
  manifest: InstallManifest,
  paths = resolveInstallStorePaths(),
): void {
  ensurePrivateDirectory(paths.cliRoot);
  const temporaryPath = `${paths.manifestPath}.tmp-${process.pid}-${Date.now()}`;
  try {
    fs.writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
    fs.renameSync(temporaryPath, paths.manifestPath);
  } finally {
    fs.rmSync(temporaryPath, { force: true });
  }
}

function assertPayloadPath(payloadPath: string, paths: InstallStorePaths): void {

View on GitHub (pinned to 67001ec6eb)

Solutions

Read the embedded inner error in the message: if it says 'unsupported manifest shape', apply error 276's fixes; if it is a SyntaxError, the JSON is malformed.
Open ~/.paperclip/cli/install.json and either repair the JSON syntax or replace the file with a known-good manifest.
If unrecoverable, remove cliRoot and reinitialize: 'rm -rf ~/.paperclip/cli && paperclipai install'.
If the inner error is EACCES, fix permissions on install.json (chown/chmod) to be readable by the current user.

Example fix

// before: install.json is truncated JSON
$ cat ~/.paperclip/cli/install.json
{ "schemaVersion": 1, "source": "np

// after
$ rm -rf ~/.paperclip/cli
$ paperclipai install

Defensive patterns

Strategy: try-catch

Validate before calling

import fs from "node:fs";
import { resolveInstallStorePaths } from "./install-store.js";

function manifestIsReadable(paths = resolveInstallStorePaths()): boolean {
  if (!fs.existsSync(paths.manifestPath)) return false;
  try { JSON.parse(fs.readFileSync(paths.manifestPath, "utf8")); return true; }
  catch { return false; }
}

Try / catch

import { readInstallManifest } from "./install-store.js";

let manifest;
try {
  manifest = readInstallManifest(paths);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Could not read managed install manifest")) {
    console.error("Manifest corrupt:", err.message);
    // prompt user; on approval reset store
    process.exit(1);
  }
  throw err;
}

Prevention

Treat install.json as binary — do not edit it with text tools that may corrupt it.
Ensure the install write completes (atomic rename) before reading the manifest.
Fix permissions (chmod/chown) on install.json if access errors appear.
Restore from backup or reinitialize if the JSON is malformed.

When it happens

Trigger: Called readInstallManifest() where reading install.json throws a non-ENOENT error: JSON.parse fails (malformed JSON), or the inner shape-validation throws 'unsupported manifest shape', or readFileSync fails with EACCES/EIO, etc. The catch re-throws with this wrapper.

Common situations: 1) install.json is truncated or contains invalid JSON (partial write, editor save race). 2) The manifest shape is wrong (see error 276 — the inner throw becomes the 'String(error)' portion of this message). 3) Permissions deny reading the file. 4) Disk I/O error mid-read.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/43810274a12844d1. Report an issue: GitHub.