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

# Troubleshooting

> Resolve missing, stale, unlinked, or misplaced 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.

## 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.

## Continue with

<CardGroup cols={2}>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find active sessions and session IDs.
  </Card>

  <Card title="Attach Sessions" icon="link" href="/guides/sessions/attach-sessions">
    Recover missed context and link it to a checkpoint.
  </Card>

  <Card title="Resume Sessions" icon="code-branch" href="/guides/sessions/resume-sessions">
    Continue previous agent work from a session or branch.
  </Card>

  <Card title="Stop Sessions" icon="circle-stop" href="/guides/sessions/stop-sessions">
    End stale or active sessions.
  </Card>
</CardGroup>