Claude Code stuck on compacting

Guide · August 2026 · ~4 min read

Long sessions periodically compact: Claude Code summarizes the conversation so far into a compact record and continues from it. When compaction hangs — spinner forever, or the session afterwards refuses to resume — the cause is almost always in the transcript file, not the model.

What a healthy compaction looks like

In the session JSONL you'll see a summary record near the end: a record whose content summarizes prior context, with the next user message parented onto it. If that structure is intact, resume works.

Failure mode 1: interrupted mid-write

Compaction writes new records. Kill the process (or lose power) during the write and the last line is truncated or a summary lands without its child. The session then either loops trying to compact again or fails to load. Find the bad line:

python -c "
import json
import os
p = os.path.expanduser('~/.claude/projects/YOUR-PROJECT/SESSION.jsonl')
for i, line in enumerate(open(p, encoding='utf-8')):
    if line.strip():
        try: json.loads(line)
        except Exception as e: print(f'line {i+1}: {e}')"

Failure mode 2: the summary is there but nothing points at it

The compact record exists but the following message still parents to the pre-compaction chain. The loader walks uuid → parentUuid from the newest leaf; if the walk never reaches the summary, the session loads with full old context (compaction silently didn't take effect) or fails outright. The fix: reparent the orphaned message onto the summary record, or delete the dangling branch.

Failure mode 3: orphaned tool results around the cut

If a tool call sat in flight when compaction started, its result can end up referencing a call that was summarized away. Same repair as any orphan: remove the result or pair it out entirely.

Recovery path

Back up the file first. SessionPatch can identify broken references and jump to their records. It can safely remove a linked tool call/result pair, and Doctor can guide a missing parentUuid repair to a proposed prior record or root. Other structural findings remain diagnostic and may still require careful manual repair.