paperclipai/paperclip · error

Workspace ignore scan failed

Error message

Workspace ignore scan failed: ${directoryIgnore.reason}

What it means

Before archiving/syncing a workspace into the sandbox, the runtime resolves the workspace's effective ignore rules via resolveReferencedSourceIgnore. When that scan fails (kind === "failed"), the runtime cannot determine which files are allowed to leave the host, so it fails loudly instead of shipping a potentially wrong file set.

Solutions

1. Fix the underlying reason reported in the message (permissions, missing dir, broken git).
2. Ensure the workspaceLocalDir exists and is readable before starting the run.
3. If git-based ignore resolution fails, repair the repository (git status / reinstall git) or provide a valid gitSnapshot path.
4. Retry after resolving transient FS issues (network mounts, stale handles).

const scan = await resolveReferencedSourceIgnore(workspaceLocalDir);
if (scan.kind === "failed") throw new Error(`workspace ignore scan failed: ${scan.reason}`);

const ignoreScanOk = (r: IgnoreScanResult): r is Exclude<IgnoreScanResult, { kind: "failed" }> => r.kind !== "failed";

try { await startManagedRuntime(input); } catch (e) {
  if (e.message.startsWith("Workspace ignore scan failed")) { console.error("fix workspace/git:", e.message); }
  throw e;
}

When it happens

Trigger: syncWorkspace is true with no gitSnapshot, and resolveReferencedSourceIgnore(input.workspaceLocalDir) returns { kind: "failed", reason }.

Common situations: Workspace directory unreadable or deleted; git not installed or repo metadata corrupt so ignore resolution fails; symlinked/network-mounted workspace causing the scanner to error; permission problems on .gitignore traversal.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• A trusted viewer build is required for public chat reports
• ACPX runtime executable changed while it was verified
• ACPX runtime executable could not be opened as a no-follow…
• ACPX runtime executable must be a bounded executable file
• ACPX runtime executable must be a real regular file

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/074fb675352c9914. Report an issue: GitHub.

Appendix: source

Thrown at packages/adapter-utils/src/sandbox-managed-runtime.ts:1151

  // The git enumeration (`git status --ignored`, the HEAD diffs, `ls-files`).
  // It reads git's own bookkeeping to decide what to include/exclude, so it is
  // usually fast, but on a large working tree the `--ignored` walk is not free.
  const gitSnapshot = syncWorkspace
    ? input.workspaceGitSnapshot !== undefined
      ? input.workspaceGitSnapshot
      : await runStepSpan("snapshot.git", () =>
          readGitWorkspaceSnapshot(input.workspaceLocalDir),
        )
    : null;
  // A selected subfolder has no cloneable Git snapshot, but its parent
  // repository's ignore rules still govern which files may leave the host.
  // Use the same bounded, path-relative resolver as referenced project trees.
  const directoryIgnore = syncWorkspace && !gitSnapshot
    ? await resolveReferencedSourceIgnore(input.workspaceLocalDir)
    : null;
  if (directoryIgnore?.kind === "failed") {
    throw new Error(`Workspace ignore scan failed: ${directoryIgnore.reason}`);
  }
  const gitIgnoredExcludes = gitSnapshot?.ignoredPaths
    ?? (directoryIgnore?.kind === "git" ? directoryIgnore.ignoredPaths : undefined);
  const workspaceArchiveExclude = mergeExcludes(
    SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES,
    [...GIT_ARCHIVE_EXCLUDES],
    input.workspaceExclude,
    gitIgnoredExcludes,
  );
  const restoreExclude = mergeExcludes(
    SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES,
    [...GIT_ARCHIVE_EXCLUDES],
    [".paperclip-runtime"],
    input.preserveAbsentOnRestore,
    input.workspaceExclude,
    gitIgnoredExcludes,
  );
  const repositories = gitSnapshot?.repositories ?? [];

View on GitHub (pinned to 3f1d897a7c)