{"record":{"id":"90b8ec1ebdfbb1be","repo":"davila7/claude-code-templates","slug":"invalid-session-file-missing-or-invalid-messages","errorCode":null,"errorMessage":"Invalid session file - missing or invalid messages","messagePattern":"Invalid session file - missing or invalid messages","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli-tool/src/session-sharing.js","lineNumber":342,"sourceCode":"    }\n  }\n\n  /**\n   * Validate session data structure\n   * @param {Object} sessionData - Session data to validate\n   * @throws {Error} If validation fails\n   */\n  validateSessionData(sessionData) {\n    if (!sessionData.version) {\n      throw new Error('Invalid session file - missing version');\n    }\n\n    if (!sessionData.conversation || !sessionData.conversation.id) {\n      throw new Error('Invalid session file - missing conversation data');\n    }\n\n    if (!sessionData.messages || !Array.isArray(sessionData.messages)) {\n      throw new Error('Invalid session file - missing or invalid messages');\n    }\n\n    if (sessionData.messages.length === 0) {\n      throw new Error('Invalid session file - no messages found');\n    }\n  }\n\n  /**\n   * Install session in Claude Code directory structure\n   * @param {Object} sessionData - Session data to install\n   * @param {Object} options - Installation options\n   * @returns {Promise<Object>} Installation result\n   */\n  async installSession(sessionData, options = {}) {\n    const homeDir = os.homedir();\n    const claudeDir = path.join(homeDir, '.claude');\n\n    // Determine project directory","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/davila7/claude-code-templates/blob/a0851ed10c7c60463dac8cfaaca124cf32d5804d/cli-tool/src/session-sharing.js#L324-L360","documentation":"Thrown by validateSessionData() in cli-tool/src/session-sharing.js when the 'messages' field of the session export is missing or not an array. The messages array is the actual conversation payload; without it there is nothing to install, so the clone is rejected before any files are written.","triggerScenarios":"Calling cloneSession()/validateSessionData() where sessionData.messages is undefined, null, or an object (e.g. a schema change renamed messages to history, or the downloaded JSON is some other export format).","commonSituations":"Claude Code schema evolution renaming the messages field; exports from third-party tools that use a different conversation format; partially written/corrupt export files.","solutions":["Inspect sessionData.messages — if the data lives under another key (e.g. 'history'), the export format differs from what this CLI expects; re-export with a matching version","Re-download the file in case of truncation","Update session-sharing.js validation to accept the current session schema"],"exampleFix":"// before\nif (!sessionData.messages || !Array.isArray(sessionData.messages)) {\n  throw new Error('Invalid session file - missing or invalid messages');\n}\n\n// after\nconst msgs = Array.isArray(sessionData.messages) ? sessionData.messages : sessionData.history;\nif (!Array.isArray(msgs)) {\n  throw new Error('Invalid session file - missing or invalid messages');\n}","handlingStrategy":"type-guard","validationCode":"if (!Array.isArray(data.messages)) {\n  throw new Error('Rejecting file: messages is not an array — wrong export format');\n}","typeGuard":"function hasMessagesArray(d) {\n  return Boolean(d) && Array.isArray(d.messages);\n}","tryCatchPattern":"try {\n  await cloner.cloneSession(data);\n} catch (e) {\n  if (e.message.includes('missing or invalid messages')) {\n    throw new Error('Export format mismatch — re-export with a matching CLI version');\n  }\n  throw e;\n}","preventionTips":["Validate the messages array type in one guard before cloning","Pin the CLI version used to export and import sessions"],"tags":["validation","session-sharing","schema","type-mismatch"],"backgroundTag":"schema-validation-failed","analyzedSha":"a0851ed10c7c60463dac8cfaaca124cf32d5804d","analyzedAt":"2026-08-28T14:11:56.058Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}