davila7/claude-code-templates · error · Error

Invalid session file - missing or invalid messages

Error message

Invalid session file - missing or invalid messages

What it means

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.

Source

Thrown at cli-tool/src/session-sharing.js:342

    }
  }

  /**
   * Validate session data structure
   * @param {Object} sessionData - Session data to validate
   * @throws {Error} If validation fails
   */
  validateSessionData(sessionData) {
    if (!sessionData.version) {
      throw new Error('Invalid session file - missing version');
    }

    if (!sessionData.conversation || !sessionData.conversation.id) {
      throw new Error('Invalid session file - missing conversation data');
    }

    if (!sessionData.messages || !Array.isArray(sessionData.messages)) {
      throw new Error('Invalid session file - missing or invalid messages');
    }

    if (sessionData.messages.length === 0) {
      throw new Error('Invalid session file - no messages found');
    }
  }

  /**
   * Install session in Claude Code directory structure
   * @param {Object} sessionData - Session data to install
   * @param {Object} options - Installation options
   * @returns {Promise<Object>} Installation result
   */
  async installSession(sessionData, options = {}) {
    const homeDir = os.homedir();
    const claudeDir = path.join(homeDir, '.claude');

    // Determine project directory

View on GitHub (pinned to a0851ed10c)

Solutions

1. 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
2. Re-download the file in case of truncation
3. Update session-sharing.js validation to accept the current session schema

Example fix

// before
if (!sessionData.messages || !Array.isArray(sessionData.messages)) {
  throw new Error('Invalid session file - missing or invalid messages');
}

// after
const msgs = Array.isArray(sessionData.messages) ? sessionData.messages : sessionData.history;
if (!Array.isArray(msgs)) {
  throw new Error('Invalid session file - missing or invalid messages');
}

if (!Array.isArray(data.messages)) {
  throw new Error('Rejecting file: messages is not an array — wrong export format');
}

function hasMessagesArray(d) {
  return Boolean(d) && Array.isArray(d.messages);
}

try {
  await cloner.cloneSession(data);
} catch (e) {
  if (e.message.includes('missing or invalid messages')) {
    throw new Error('Export format mismatch — re-export with a matching CLI version');
  }
  throw e;
}

When it happens

Trigger: 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).

Common situations: Claude Code schema evolution renaming the messages field; exports from third-party tools that use a different conversation format; partially written/corrupt export files.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid session file - missing version
• Invalid session file - missing conversation data
• Invalid session file - no messages found
• Invalid workflow hash format. Expected format: #hash
• Invalid hash format: missing encoded data

AI-assisted analysis of davila7/claude-code-templates@a0851ed10c (2026-08-28). Data as JSON: /api/errors/90b8ec1ebdfbb1be. Report an issue: GitHub.