[DOCS] Session documentation omits warnings for failed transcript writes and disabled persistence

Status Fixed / completed

Reported on v2.1.217

Maintainer reply ✓ Yes — bcherny

Activity 3 comments · opened Jul 22, 2026 · closed Aug 16, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sessions

Section/Topic

The session persistence introduction, Where transcripts are stored, and the troubleshooting guidance for transcript writes.

Current Documentation

The page currently says:

Sessions are saved continuously to local transcript files as you work, so you can return to one after exiting or running /clear.

Its configuration table documents only the controls that suppress writes:

Suppress transcript writes in all modes | CLAUDE_CODE_SKIP_PROMPT_HISTORY | Environment variable

Suppress writes for one non-interactive run | --no-session-persistence | CLI flag with claude -p

The environment-variable reference explains that CLAUDE_CODE_CHILD_SESSION can exclude a nested interactive session from resume history and that CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 overrides that exclusion, but the sessions page does not explain the warning shown when persistence is disabled or when a transcript write fails.

What's Wrong or Missing?

Claude Code v2.1.217 adds warnings when transcript writes fail, such as when the disk is full, and when session saving is disabled because an inherited environment variable turns persistence off. This prevents users from assuming that the continuously-saved-session guarantee still holds after writes have stopped.

The sessions page describes sessions as being saved continuously and lists opt-out controls, but it does not explain the new warning condition, how to distinguish an intentional persistence opt-out from a failed write, or what recovery steps to take. A user who sees the warning has no documented path to check disk capacity and permissions, inspect inherited environment variables, or restore persistence when the disabling condition is accidental.

Suggested Improvement

Add a Transcript persistence warnings subsection to the sessions page that:

Explains that Claude Code warns when it cannot write a transcript instead of silently continuing without a current transcript.
Gives the common recovery steps for a write failure, including checking available disk space, the transcript directory, and write permissions.
Explains that an inherited persistence-related environment variable can intentionally or accidentally disable session saving.
Links to the relevant environment-variable rows, including CLAUDE_CODE_SKIP_PROMPT_HISTORY, CLAUDE_CODE_CHILD_SESSION, and CLAUDE_CODE_FORCE_SESSION_PERSISTENCE, and explains when the override is appropriate.
States what happens to --resume, --continue, /resume, and prompt history while persistence is disabled.

Add a short cross-reference from the environment-variable descriptions back to this troubleshooting section.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sessions | 9, 15, 149-158 | Continuous-save description and transcript write configuration table |
| https://code.claude.com/docs/en/env-vars | 189, 245, 315 | Inherited child-session behavior, forced persistence, and prompt-history suppression |

Total scope: 2 pages should explain the same persistence-warning and recovery behavior.

The relevant release is Claude Code v2.1.217. The release entry is listed in the Claude Code changelog under version 2.1.217.

View original on GitHub ↗

3 Comments

mcccsm · 2 months ago

Adding a real-world datapoint that supports documenting this failure mode, plus a specific gap: inherited CLAUDE_CODE_CHILD_SESSION silently disabling persistence, with no warning surfaced.

Environment: Claude Code v2.1.218, Linux, native install, interactive CLI.

What happened

A kitty terminal window was (at some earlier point) spawned from inside a Claude Code session. That terminal's environment therefore carried CLAUDE_CODE_CHILD_SESSION=1 (verified via /proc/<pid>/environ on the terminal PID, not just the claude PID). Every interactive claude subsequently started in that window inherited the flag and was treated as a nested/child session.

Result for those sessions:

No ~/.claude/projects/<project>/<session-id>.jsonl transcript was ever written.
No entries were appended to ~/.claude/history.jsonl.
Only side-effects persisted: per-tool tool-results/*.txt files and the actual project files the session edited.
One .jsonl that did exist from a prior (persisted) session had its mtime bumped with no new content appended, which made the folder look "recently active" during forensics.

The user only discovered the loss after /clear, when the conversation could not be resumed. Sessions launched in a clean terminal (child=0) in the same account persisted normally, which is what pointed to the env var.

Why this is worth a doc + UX note

The current docs promise sessions are "saved continuously ... so you can return to one after exiting or running /clear." That guarantee silently does not hold when CLAUDE_CODE_CHILD_SESSION is inherited. Crucially, the inheritance is easy to hit by accident: opening a terminal from within a Claude Code session marks that terminal, so it is not obviously a "nested" session from the user's point of view — it looks like a normal primary session.

On v2.1.218 no visible warning was surfaced for this specific disabling condition (inherited CLAUDE_CODE_CHILD_SESSION), even though 2.1.217 reportedly added transcript-write/persistence-disabled warnings.

Suggestions (in addition to the doc section proposed above)

Surface a persistent, visible indicator (status line / startup banner) when the current interactive session is non-persisting because CLAUDE_CODE_CHILD_SESSION is set, distinct from a one-off write failure.
Document that a terminal opened from within a Claude Code session inherits this flag, and that CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 (or unsetting CLAUDE_CODE_CHILD_SESSION before launch) restores persistence.
Consider warning specifically before /clear on a non-persisting session, since that is the point of irreversible loss.

bcherny collaborator · 1 month ago

Thanks — these warnings are documented on the errors page under "Session saving warnings". It covers the Transcript writes are failing (...) warning (which error codes trigger it, when it appears, and how to recover: free disk space, clear quota, restore write access) and the Transcript saving is off warnings for CLAUDE_CODE_SKIP_PROMPT_HISTORY and an inherited CLAUDE_CODE_CHILD_SESSION marker, including the CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 override:

https://code.claude.com/docs/en/errors#session-saving-warnings

Closing as documented.

🤖 Generated with Claude Code

github-actions[bot] · 9 days ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.