JuliusBrussee/caveman · error · Error

local learn snapshot has no sinks array at ${snapshotPath}

Error message

local learn snapshot has no sinks array at ${snapshotPath}

What it means

The learn snapshot JSON parsed successfully but lacks the expected sinks array. The sync protocol requires a sinks list (empty snapshots are sent to clear stale rows), so a malformed snapshot is rejected.

Source

Thrown at packages/cli/src/index.ts:10062

  return `${subject} · ${out.tokensSaved} estimated tokens saved (inferred; counter basis ${out.tokenCountBasis})${destination}`;
}

// syncLocalPracticeFindings moves only stable ids + non-negative token rates
// from the current learn snapshot. Titles, suggestions, evidence, file paths,
// and payload text never leave the machine. Empty snapshots are sent so stale
// rows for this user are removed server-side.
async function syncLocalPracticeFindings(cfg: Config): Promise<PracticeSyncOutcome> {
  const snapshotPath = join(cavemanHome(), "reports", "caveman-learn.json");
  let raw: Record<string, unknown>;
  try {
    raw = JSON.parse(readFileSync(snapshotPath, "utf8")) as Record<string, unknown>;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "no_snapshot" };
    throw new Error(`local learn snapshot is unreadable at ${snapshotPath}`);
  }

  if (!Array.isArray(raw.sinks)) {
    throw new Error(`local learn snapshot has no sinks array at ${snapshotPath}`);
  }
  const observed = typeof raw.generated_at === "string" ? new Date(raw.generated_at) : null;
  if (!observed || Number.isNaN(observed.valueOf())) {
    throw new Error(`local learn snapshot has no valid generated_at at ${snapshotPath}`);
  }
  const sessions = typeof raw.sessions_scanned === "number" && Number.isFinite(raw.sessions_scanned)
    ? Math.max(0, Math.trunc(raw.sessions_scanned))
    : 0;
  const counter = (value: unknown) =>
    typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;

  const findings = raw.sinks
    .filter((sink): sink is Record<string, unknown> =>
      !!sink && typeof sink === "object" && !Array.isArray(sink))
    .filter((sink) => typeof sink.practice_id === "string" && sink.practice_id.length > 0)
    .map((sink) => ({
      sink_id: typeof sink.sink_id === "string" ? sink.sink_id : "",
      practice_id: sink.practice_id as string,

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Regenerate the snapshot with the current `caveman learn` version
2. Verify no hand edits removed the sinks field from caveman-learn.json

When it happens

Trigger: Thrown at packages/cli/src/index.ts:9217 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-08-18). Data as JSON: /api/errors/a86996468ce1baea. Report an issue: GitHub.