{"record":{"id":"887a671ef7bcc037","repo":"vercel/ai","slug":"unsupported-deep-agents-conversation-checkpoint-fo","errorCode":null,"errorMessage":"Unsupported Deep Agents conversation checkpoint format","messagePattern":"Unsupported Deep Agents conversation checkpoint format","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-deepagents/src/bridge/persistent-memory-saver.ts","lineNumber":40,"sourceCode":"\nexport async function loadMemorySaver({\n  path,\n  saver,\n}: {\n  path: string;\n  saver: MemorySaver;\n}): Promise<void> {\n  let snapshot: string;\n  try {\n    snapshot = await readFile(path, 'utf8');\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;\n    throw error;\n  }\n\n  const [header, ...lines] = snapshot.split('\\n');\n  if (header !== SNAPSHOT_HEADER) {\n    throw new Error('Unsupported Deep Agents conversation checkpoint format');\n  }\n\n  const storage: MemorySaver['storage'] = Object.create(null);\n  const writes: MemorySaver['writes'] = Object.create(null);\n\n  for (const line of lines) {\n    if (line === '') continue;\n    const fields = line.split('\\t');\n    if (fields[0] === 'S' && fields.length === 7) {\n      const [, threadIdValue, namespaceValue, checkpointIdValue] = fields;\n      const threadId = decodeString(threadIdValue);\n      const namespace = decodeString(namespaceValue);\n      const checkpointId = decodeString(checkpointIdValue);\n      storage[threadId] ??= Object.create(null);\n      storage[threadId][namespace] ??= Object.create(null);\n      storage[threadId][namespace][checkpointId] = [\n        decodeBytes(fields[4]),\n        decodeBytes(fields[5]),","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-deepagents/src/bridge/persistent-memory-saver.ts#L22-L58","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Delete the stale `conversation.checkpoint` in the session's `bridge` state directory (`.agent-runs/<sessionId>/bridge/`) and start a fresh session.","Use a harness package version compatible with the one that wrote the checkpoint (match the format version `deepagents-memory-saver-v1`).","If you must keep history, export/convert the old snapshot to the current header format before resuming.","Inspect the file's first line (`head -1 conversation.checkpoint`) to confirm what format it actually is."],"exampleFix":"// discard incompatible checkpoint and start fresh\nrm .agent-runs/<sessionId>/bridge/conversation.checkpoint","handlingStrategy":"fallback","validationCode":"const header = (await readFile(path, 'utf8').catch(() => '')).split('\\n')[0];\nconst compatible = header === 'deepagents-memory-saver-v1' || header === '';","typeGuard":null,"tryCatchPattern":"try {\n  await resumeSession();\n} catch (error) {\n  if (error instanceof Error && error.message.includes('Unsupported')) {\n    // back up the old checkpoint, delete it, start a fresh session\n  }\n  throw error;\n}","preventionTips":["Keep harness package versions consistent across sessions","Back up checkpoints before upgrading","Never hand-edit checkpoint files","Check the file header before resuming an old session"],"tags":["persistence","versioning","checkpoint"],"backgroundTag":"unsupported-checkpoint-format","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}