> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve missing, stale, or unlinked sessions, and fix checkpoint capture, linking, and sync issues.

Use this page when a session is missing or stale, a checkpoint was not created, or a checkpoint did not link or sync where you expected.

## Sessions

> **No Active Session Appears**
>
> Check repository and hook status:
>
> ```bash theme={null}
> entire status
> ```
>
> If Entire is not enabled, start with:
>
> ```bash theme={null}
> entire enable --agent AGENT
> ```
>
> If Entire is already enabled but the agent is not configured, add it:
>
> ```bash theme={null}
> entire agent add AGENT
> ```
>
> Then start your agent from inside the enabled repository. Agent hooks only capture work for agents that are configured for that repo.

> **The Session Did Not Link to a Commit**
>
> A normal committed checkpoint needs both captured session context and a Git commit.
>
> If the session exists but was not linked, attach it to the latest commit:
>
> ```bash theme={null}
> entire session attach SESSION_ID --agent AGENT
> ```
>
> If the commit already has a checkpoint, Entire adds the session to that checkpoint. Otherwise, Entire can create a new checkpoint and amend the commit with an `Entire-Checkpoint` trailer. See [Attach Sessions](/guides/sessions/attach-sessions) for the full flow.

> **The Session Is Attached to the Wrong Worktree**
>
> If an agent started in one worktree and continued in another, adopt the session into the current repository:
>
> ```bash theme={null}
> entire session adopt SESSION_ID --from ../source-worktree
> ```
>
> After adoption, the next commit can link to the session normally.

> **Stale Sessions Keep Showing Up**
>
> Use `entire status` to find active and stale sessions. If a session is no longer running, stop it:
>
> ```bash theme={null}
> entire session stop SESSION_ID
> ```
>
> For multiple stale sessions:
>
> ```bash theme={null}
> entire session stop --all
> ```
>
> If status suggests a repository health issue, run:
>
> ```bash theme={null}
> entire doctor
> ```

> **Token Usage Is Missing**
>
> Token usage depends on what the agent exposes and when the session data is available. Some agents only expose full token usage after the session ends.
>
> Check the session details first:
>
> ```bash theme={null}
> entire session info SESSION_ID
> ```
>
> Then check token usage:
>
> ```bash theme={null}
> entire session tokens SESSION_ID
> ```

> **The Raw Transcript Is Missing**
>
> Entire reads transcript data from the agent's session storage. If the agent deleted or moved its local transcript, Entire may still have metadata but not the raw transcript bytes.
>
> Try:
>
> ```bash theme={null}
> entire session info SESSION_ID --json
> ```
>
> If metadata exists but the transcript cannot be streamed, inspect the relevant [agent guide](/agents/overview) for that agent's transcript requirements.

## Checkpoints

> **Run a Checkpoint Health Check**
>
> Start with `entire doctor` when `entire status` shows a stale or exited session, checkpoint commands seem to miss data, or you see warnings about metadata branches.
>
> ```bash theme={null}
> entire doctor
> ```
>
> `entire doctor` can repair some metadata branch issues and condense stuck sessions into permanent checkpoint storage. It does not fix every checkpoint issue: use [Attach Sessions](/guides/sessions/attach-sessions) for missing commit trailers, and check remote or GitHub permissions for sync problems.
>
> To move checkpoints off the `entire/checkpoints/v1` branch and into per-checkpoint refs, see [Migrate Existing Checkpoints into Refs](/guides/checkpoints/checkpoint-storage#migrate-existing-checkpoints-into-refs).

> **No Checkpoint Appears After a Commit**
>
> A checkpoint is created when Entire can connect a Git commit to captured agent session context.
>
> Check these first:
>
> * Run `entire status` to confirm Entire is enabled in the repository
> * Confirm the repo was set up with `entire enable` or `entire configure`
> * If you committed from a GUI Git client, configure [absolute Git hook paths](/guides/configuration/git-hooks#gui-git-clients)
> * If the agent session started before hooks were installed, start a new session after setup
>
> If Entire captured the session but did not link it automatically, attach it manually:
>
> ```bash theme={null}
> entire session attach SESSION_ID -a AGENT
> ```
>
> See [Attach Sessions](/guides/sessions/attach-sessions) for the full flow.

> **The Commit Is Missing the Checkpoint Trailer**
>
> Entire links a commit to a checkpoint with an `Entire-Checkpoint` trailer.
>
> If the trailer is missing:
>
> * The commit may have happened before Entire was enabled
> * The prompt to link the session may have been declined
> * The session may have been created in another folder
> * Git hooks may not have run
>
> Use `entire checkpoint list` to see whether the checkpoint exists locally. If the session exists but the commit is not linked, use [Attach Sessions](/guides/sessions/attach-sessions).

> **The Checkpoint Appears Locally but Not in entire.io**
>
> entire.io reads checkpoint data after you push it: the per-checkpoint refs on the ref-based backend, or the `entire/checkpoints/v1` branch on the branch-based backend.
>
> Try this:
>
> 1. Run `git push`
> 2. Watch for any Entire warnings during the push
> 3. Confirm `push_sessions` is enabled in [checkpoint storage settings](/guides/checkpoints/checkpoint-storage)
> 4. Confirm the checkpoints reached the remote with `git ls-remote origin 'refs/entire/checkpoints/*'`, or `git ls-remote origin entire/checkpoints/v1` on the branch-based backend
> 5. Confirm the Entire GitHub App can access the repository
>
> For GitHub App access issues, see [Install the Entire GitHub App](/guides/repositories/github-app-access). For checkpoint push behavior, see [Session Storage](/guides/checkpoints/checkpoint-storage).

> **Checkpoint Data Is Going to the Wrong Place**
>
> By default, Entire pushes checkpoint data to the same remote as your code. If your team stores checkpoint data in a separate repository, configure a checkpoint remote.
>
> Check `.entire/settings.json` for:
>
> ```json theme={null}
> {
>   "strategy_options": {
>     "checkpoint_remote": {
>       "provider": "github",
>       "repo": "myorg/checkpoints-private"
>     }
>   }
> }
> ```
>
> See [checkpoint remote](/guides/checkpoints/store-checkpoints-in-another-repo) for setup details.

> **Checkpoint Remote Did Not Sync**
>
> Checkpoint remote failures do not block your main Git push. Entire saves checkpoint data locally and warns when it cannot push it.
>
> Common causes:
>
> * You do not have write access to the checkpoint remote
> * The checkpoint remote repository does not exist
> * `.entire/settings.json` was not committed, so teammates or entire.io cannot discover the setting
> * You are pushing from a fork, and fork detection skipped the organization checkpoint remote
>
> For checkpoint remote owner rules and push behavior, see [Store Checkpoints in Another Repository](/guides/checkpoints/store-checkpoints-in-another-repo).

> **A Squash Merge Lost the Checkpoint Link**
>
> Some Git hosts can remove commit trailers during squash merges. If the `Entire-Checkpoint` trailer is removed, Entire cannot link the squashed commit back to its checkpoint metadata.
>
> For GitLab squash merges, configure the squash commit message template under Settings > Repository > Merge requests.
>
> Use a template that includes the squashed commit content, for example:
>
> ```text theme={null}
> %{title} (%{reference})
>
> %{all_commits}
> ```

> **A Checkpoint Shows Unknown Author in entire.io**
>
> entire.io shows `Unknown author` when the commit behind a checkpoint has no author identity that GitHub can match to a user. This usually means the commit was authored with an unexpected Git identity, the author email is not associated with a GitHub account, or GitHub returned commit metadata without a matched username.
>
> Set your Git author identity to an email associated with your GitHub account, then create and push a new commit:
>
> ```bash theme={null}
> git config user.email you@example.com
> ```
>
> `.entire/settings.json` does not affect commit author identity. Only your Git config does.

> **Still Stuck?**
>
> Include these details when asking for help:
>
> * `entire version`
> * the agent you were using
> * whether the checkpoint appears in `entire checkpoint list`
> * the checkpoint ID, if there is one
> * any warning printed during `git commit` or `git push`
>
> You can file an issue at [github.com/entireio/cli](https://github.com/entireio/cli) or ask in the [Entire Discord](https://discord.gg/jZJs3Tue4S).

## Continue With

> **[List Sessions](/guides/sessions/list-sessions)**
>
> Find active sessions and session IDs.

> **[Attach Sessions](/guides/sessions/attach-sessions)**
>
> Recover missed context and link it to a checkpoint.

> **[Stop Sessions](/guides/sessions/stop-sessions)**
>
> End stale or active sessions.

> **[Capture Sessions and Their Checkpoints](/guides/checkpoints/capture-checkpoints)**
>
> Learn how Entire captures agent sessions and turns them into committed checkpoints.

> **[Storage Backends](/guides/checkpoints/checkpoint-storage)**
>
> Choose between a Git ref and the checkpoints branch.

> **[Inspect Checkpoints](/guides/checkpoints/inspect-checkpoints)**
>
> Open a checkpoint from the CLI or entire.io.