vercel/ai · error

Unsupported Deep Agents conversation checkpoint format

Error message

Unsupported Deep Agents conversation checkpoint format

What it means

On resume (`--resume true`), the bridge loads a persisted LangGraph `MemorySaver` snapshot from `conversation.checkpoint`. The file's first line must be the exact header `deepagents-memory-saver-v1`; any other header means the file was written by an incompatible (older/newer) format, so the bridge refuses to load it rather than misinterpreting checkpoint data.

Source

Thrown at packages/harness-deepagents/src/bridge/persistent-memory-saver.ts:40

export async function loadMemorySaver({
  path,
  saver,
}: {
  path: string;
  saver: MemorySaver;
}): Promise<void> {
  let snapshot: string;
  try {
    snapshot = await readFile(path, 'utf8');
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
    throw error;
  }

  const [header, ...lines] = snapshot.split('\n');
  if (header !== SNAPSHOT_HEADER) {
    throw new Error('Unsupported Deep Agents conversation checkpoint format');
  }

  const storage: MemorySaver['storage'] = Object.create(null);
  const writes: MemorySaver['writes'] = Object.create(null);

  for (const line of lines) {
    if (line === '') continue;
    const fields = line.split('\t');
    if (fields[0] === 'S' && fields.length === 7) {
      const [, threadIdValue, namespaceValue, checkpointIdValue] = fields;
      const threadId = decodeString(threadIdValue);
      const namespace = decodeString(namespaceValue);
      const checkpointId = decodeString(checkpointIdValue);
      storage[threadId] ??= Object.create(null);
      storage[threadId][namespace] ??= Object.create(null);
      storage[threadId][namespace][checkpointId] = [
        decodeBytes(fields[4]),
        decodeBytes(fields[5]),

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Delete the stale `conversation.checkpoint` in the session's `bridge` state directory (`.agent-runs/<sessionId>/bridge/`) and start a fresh session.
2. Use a harness package version compatible with the one that wrote the checkpoint (match the format version `deepagents-memory-saver-v1`).
3. If you must keep history, export/convert the old snapshot to the current header format before resuming.
4. Inspect the file's first line (`head -1 conversation.checkpoint`) to confirm what format it actually is.

Example fix

// discard incompatible checkpoint and start fresh
rm .agent-runs/<sessionId>/bridge/conversation.checkpoint

const header = (await readFile(path, 'utf8').catch(() => '')).split('\n')[0];
const compatible = header === 'deepagents-memory-saver-v1' || header === '';

try {
  await resumeSession();
} catch (error) {
  if (error instanceof Error && error.message.includes('Unsupported')) {
    // back up the old checkpoint, delete it, start a fresh session
  }
  throw error;
}

When it happens

Trigger: Resuming a session whose `conversation.checkpoint` was written by a different deepagents bridge version, or whose checkpoint file is corrupted/truncated/overwritten (first line no longer matches the v1 header).

Common situations: Upgrading or downgrading the harness package between sessions and resuming an old conversation; the checkpoint file being manually edited or clobbered by another process; a partially written file after a crash (though saves use atomic rename).

Related errors

• Invalid Deep Agents conversation checkpoint
• Unsupported ACP protocol version ${JSON.stringify(version)}.
• ACP lifecycle state data is missing.
• OAuth authorization server metadata must be saveable before

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/887a671ef7bcc037. Report an issue: GitHub.