davila7/claude-code-templates · error · Error

Invalid session file - missing version

Error message

Invalid session file - missing version

What it means

Thrown by validateSessionData() in cli-tool/src/session-sharing.js when the parsed session object lacks a top-level 'version' field. Every Claude Code session export must carry a version identifying its schema; its absence means the JSON is valid but is not a session export (or is an unversioned/corrupted one).

Source

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

      // Parse JSON response
      const sessionData = JSON.parse(stdout);
      return sessionData;
    } catch (error) {
      if (error.message.includes('Unexpected token')) {
        throw new Error('Invalid session file - corrupted or not a Claude Code session');
      }
      throw error;
    }
  }

  /**
   * 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

View on GitHub (pinned to a0851ed10c)

Solutions

1. Inspect the downloaded JSON (Object.keys) and confirm it looks like a session export with version/conversation/messages
2. Re-share the session with the current CLI version so the export includes 'version'
3. Verify you are downloading the exact URL returned by uploadToX0, not a directory listing or other file

Example fix

// before
if (!sessionData.version) {
  throw new Error('Invalid session file - missing version');
}

// after
if (!sessionData.version) {
  throw new Error(`Invalid session file - missing version (keys found: ${Object.keys(sessionData).join(', ')})`);
}

const data = JSON.parse(raw);
if (!('version' in data)) {
  throw new Error('Not a session export: missing version field');
}

function isSessionExport(d) {
  return Boolean(d) && typeof d === 'object'
    && typeof d.version !== 'undefined'
    && d.conversation && typeof d.conversation.id === 'string'
    && Array.isArray(d.messages);
}

try {
  cloner.cloneSession(data);
} catch (e) {
  if (/Invalid session file/.test(e.message)) {
    console.error('The downloaded file is not a valid session export:', e.message);
    return; // recoverable: ask user for a correct link
  }
  throw e;
}

When it happens

Trigger: Calling cloneSession()/validateSessionData() on JSON that parses fine but has no 'version' key — e.g. downloading the wrong file, a hand-edited export, or a JSON error payload from the hosting service.

Common situations: Pointing downloadSession at an arbitrary JSON file instead of a session export; session exports produced by incompatible/older tooling that omitted the version field; keys stripped by manual editing.

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 conversation data
• Invalid session file - missing or invalid messages
• 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/ed4bf2c2cb4699b1. Report an issue: GitHub.