paperclipai/paperclip · error · Error

Timed out waiting for Paperclip skill materialization lock…

Error message

Timed out waiting for Paperclip skill materialization lock at ${lockDir}

What it means

Error "Timed out waiting for Paperclip skill materialization lock at ${lockDir}" thrown in paperclipai/paperclip.

Solutions

1. Remove the stale materialization lock at ${lockDir} if no process holds it, then retry.
2. Wait for the concurrent materialization to finish and retry.

When it happens

Trigger: Thrown at packages/adapter-utils/src/server-utils.ts:3105 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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

Appendix: source

Thrown at packages/adapter-utils/src/server-utils.ts:4206

      ? { ...(raw as Record<string, unknown>) }
      : {};
  const entries = desiredSkills.flatMap(
    (value): PaperclipDesiredSkillEntry[] => {
      if (typeof value === "string") {
        const key = value.trim();
        return key ? [{ key, versionId: null }] : [];
      }
      const key = value.key.trim();
      if (!key) return [];
      return [{ key, versionId: value.versionId ?? null }];
    },
  );
  const byKey = new Map<string, PaperclipDesiredSkillEntry>();
  for (const entry of entries) {
    if (!byKey.has(entry.key)) byKey.set(entry.key, entry);
  }
  const normalized = Array.from(byKey.values());
  current.desiredSkills = normalized.some((entry) => entry.versionId)
    ? normalized
    : normalized.map((entry) => entry.key);
  next.paperclipSkillSync = current;
  return next;
}

export async function ensurePaperclipSkillSymlink(
  source: string,
  target: string,
  linkSkill: (source: string, target: string) => Promise<void> = (
    linkSource,
    linkTarget,
  ) => fs.symlink(linkSource, linkTarget),
): Promise<"created" | "repaired" | "skipped"> {
  const existing = await fs.lstat(target).catch(() => null);
  if (!existing) {
    await linkSkill(source, target);
    return "created";

View on GitHub (pinned to 3f1d897a7c)