affaan-m/ECC · error · Error

Unsupported session file

Error message

Unsupported session file: ${sessionPath}

What it means

hydrateSessionFromPath in scripts/lib/session-adapters/claude-history.js throws this when the session file's basename cannot be parsed by sessionManager.parseSessionFilename. Only files whose names match the expected session naming convention (e.g. UUID-based .jsonl session files) are supported by the Claude history adapter; anything else is rejected up front before reading content.

Solutions

1. Verify the filename matches the expected session naming convention (run sessionManager.parseSessionFilename on path.basename(sessionPath) to see why it fails).
2. Restore the original session filename if the file was renamed — session files must keep their canonical UUID-based name and extension.
3. Point the caller at a supported session file: list the directory and choose a file that parses.
4. If you need custom formats, add an adapter for them instead of forcing them through the Claude history hydrator.

Example fix

// before
hydrateSessionFromPath('/root/.claude/projects/x/renamed-session.jsonl');
// after
const filename = path.basename(sessionPath);
if (!sessionManager.parseSessionFilename(filename)) {
  throw new Error(`Not a Claude session file: ${sessionPath}`);
}
hydrateSessionFromPath(sessionPath); // e.g. .../<uuid>.jsonl

const parsed = sessionManager.parseSessionFilename(path.basename(sessionPath));
if (!parsed) throw new Error(`Not a supported session file: ${sessionPath}`);

function isSupportedSessionFile(sessionPath) { return !!sessionManager.parseSessionFilename(path.basename(sessionPath)); }

try { const session = hydrateSessionFromPath(sessionPath); } catch (err) { if (String(err.message).startsWith('Unsupported session file:')) { console.warn('Skipping unrecognized session file:', sessionPath); return null; } throw err; }

When it happens

Trigger: Calling hydrateSessionFromPath (via resolveSessionRecord) with a path whose filename is not a recognized session file — wrong extension, non-UUID name, exported/renamed files, or a directory path.

Common situations: Pointing the resolver at ~/.claude/projects JSONL files that were renamed or truncated; passing an agent transcript or sidechain file that uses a different naming scheme; version drift where the session filename format changed between Claude Code versions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot delete active session
• Cannot merge active session
• Cannot rebase active session
• Canonical session snapshot requires
• Claude session not found

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/3d1478ed02dfaa67. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/session-adapters/claude-history.js:39

  return null;
}

function isSessionFileTarget(target, cwd) {
  if (typeof target !== 'string' || target.length === 0) {
    return false;
  }

  const absoluteTarget = path.resolve(cwd, target);
  return fs.existsSync(absoluteTarget)
    && fs.statSync(absoluteTarget).isFile()
    && absoluteTarget.endsWith('.tmp');
}

function hydrateSessionFromPath(sessionPath) {
  const filename = path.basename(sessionPath);
  const parsed = sessionManager.parseSessionFilename(filename);
  if (!parsed) {
    throw new Error(`Unsupported session file: ${sessionPath}`);
  }

  const content = sessionManager.getSessionContent(sessionPath);
  const stats = fs.statSync(sessionPath);

  return {
    ...parsed,
    sessionPath,
    content,
    metadata: sessionManager.parseSessionMetadata(content),
    stats: sessionManager.getSessionStats(content || ''),
    size: stats.size,
    modifiedTime: stats.mtime,
    createdTime: stats.birthtime || stats.ctime
  };
}

function resolveSessionRecord(target, cwd) {

View on GitHub (pinned to 8321021c54)