Claude Code ガイド

Appearance

破損トランスクリプトファイルによるセッション再開ハング問題の修正 ​

原文（日本語に翻訳） ​

parentUuidサイクルを含む破損したトランスクリプトファイルでセッションを再開する際のハング問題を修正しました。

原文（英語） ​

Fixed a hang when resuming sessions with corrupted transcript files containing parentUuid cycles

概要 ​

セッションのトランスクリプトファイルが破損し、parentUuid フィールドに循環参照が含まれている場合、Claude Code が無限ループに陥ってセッション再開時にハングする問題が修正されました。この修正により、破損したセッションデータからも安全に回復できるようになりました。

基本的な使い方 ​

セッション再開の正常動作 ​

bash
# 過去のセッションを再開
claude --resume

# セッション選択画面で過去のセッションを選択

# 以前の問題:
# - 破損したトランスクリプトがあるとハング
# - Ctrl+C でも終了できない場合がある
# - セッションが使用不可能になる

# 修正後:
# - 破損を検出して自動スキップまたは修復
# - 正常なセッションのみ表示
# - エラーメッセージで通知

最新セッションの継続 ​

bash
# 前回のセッションを続ける
claude --continue

# 最新セッションが破損している場合
# 以前: ハングして起動不可
# 現在: エラーメッセージを表示し、代替セッションを提案

実践例 ​

異常終了後のリカバリー ​

Claude Code が異常終了した後の復旧：

bash
# 前回のセッションで異常終了（クラッシュ、強制終了など）
# トランスクリプトファイルが不完全な状態で保存

# 翌日、セッションを再開しようとする
claude --continue

# 以前の動作:
# - ファイル読み込み開始
# - parentUuid循環参照を検出できず無限ループ
# - CPU 100%、メモリ増加
# - 手動でプロセスkillが必要

# 修正後の動作:
# - ファイル読み込み開始
# - 循環参照を検出
# - エラーメッセージ: "Session transcript corrupted. Using backup..."
# - 自動的にバックアップから復元、またはスキップ

複数セッションの管理 ​

多数のセッション履歴がある場合：

bash
# セッション選択画面を開く
claude --resume

# 50個のセッション履歴が存在
# うち3個のトランスクリプトが破損

# 以前:
# - 破損したセッションでハング
# - セッション一覧が表示されない

# 現在:
# - 破損セッションはスキップ
# - 正常な47セッションが一覧表示
# - 警告メッセージ: "3 sessions skipped due to corruption"

トランスクリプトの自動修復 ​

bash
# Claude Code は破損検出時に自動修復を試みる

claude --continue

# 内部処理:
# 1. トランスクリプトファイルを読み込み
# 2. parentUuid 循環参照を検出
# 3. 循環を切断して線形構造に修復
# 4. 修復版でセッション再開
# 5. 元ファイルはバックアップとして保存

# ユーザーには透過的に処理される

バックアップからの復元 ​

自動修復が不可能な場合：

bash
# セッション再開試行
claude --resume

# 重度の破損が検出される
# エラーメッセージ:
# "Session transcript severely corrupted.
#  Attempting restore from backup..."

# Claude Code は自動バックアップから復元
# ~/.claude/*.jsonl.backup* （最新5世代を保持）

# 復元成功: セッションが利用可能に
# 復元失敗: セッションを一覧から除外

手動での破損確認 ​

セッションが破損しているか確認したい場合：

bash
# トランスクリプトファイルを確認
ls -la ~/.claude/projects/*/transcript.jsonl

# 破損の可能性がある兆候:
# - ファイルサイズが異常に大きい
# - 最終更新日時が異常

# 検証（v2.1.30以降は自動実行）
# 循環参照がないか確認される

注意点 ​

  • parentUuid とは: セッションのメッセージツリー構造を管理するための内部ID。各メッセージは親メッセージへの参照を持ちます。

  • 循環参照の発生原因:

    • アプリケーションクラッシュ時の不完全な書き込み
    • ディスク容量不足
    • ファイルシステムエラー
    • 複数プロセスによる同時書き込み

  • 自動バックアップ: Claude Code はトランスクリプトファイルを自動的にバックアップし、最新5世代を保持します：

    ~/.claude/projects/my-project/transcript.jsonl
~/.claude/projects/my-project/transcript.jsonl.backup1
~/.claude/projects/my-project/transcript.jsonl.backup2
...

  • 修復の優先順位:

    1. 自動修復（循環の切断）
    2. 最新バックアップから復元
    3. セッションをスキップ

  • データ損失の可能性: 重度の破損の場合、セッションの一部のメッセージが失われる可能性があります。重要なセッションは定期的に /export でバックアップすることを推奨します。

  • パフォーマンスへの影響: v2.1.30では、セッション読み込みが68%高速化されており、破損検出も効率的に行われます。

  • トラブルシューティング: セッション再開で問題が続く場合：

    bash
    # デバッグモードで詳細を確認
claude --resume --verbose

# または、破損セッションを手動で削除
rm -rf ~/.claude/projects/<session-id>/

関連情報 ​