Troubleshooting

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:

entire status

If Entire is not enabled, start with:

entire enable --agent AGENT

If Entire is already enabled but the agent is not configured, add it:

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:

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 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:

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:

entire session stop SESSION_ID

For multiple stale sessions:

entire session stop --all

If status suggests a repository health issue, run:

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:

entire session info SESSION_ID

Then check token usage:

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:

entire session info SESSION_ID --json

If metadata exists but the transcript cannot be streamed, inspect the relevant agent guide 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.

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

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
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:

entire session attach SESSION_ID -a AGENT

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

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:

Run git push
Watch for any Entire warnings during the push
Confirm push_sessions is enabled in checkpoint storage settings
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
Confirm the Entire GitHub App can access the repository

For GitHub App access issues, see Install the Entire GitHub App. For checkpoint push behavior, see Session 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:

{
  "strategy_options": {
    "checkpoint_remote": {
      "provider": "github",
      "repo": "myorg/checkpoints-private"
    }
  }
}

See checkpoint remote 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.

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:

%{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:

git config user.email [email protected]

.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 or ask in the Entire Discord.

Continue With

List Sessions

Find active sessions and session IDs.

Attach Sessions

Recover missed context and link it to a checkpoint.

Stop Sessions

End stale or active sessions.

Capture Sessions and Their Checkpoints

Learn how Entire captures agent sessions and turns them into committed checkpoints.

Storage Backends

Choose between a Git ref and the checkpoints branch.

Inspect Checkpoints

Open a checkpoint from the CLI or entire.io.

Getting Started

Guides

Security

Resources

Troubleshooting

Sessions

Checkpoints

Continue With

List Sessions

Attach Sessions

Stop Sessions

Capture Sessions and Their Checkpoints

Storage Backends

Inspect Checkpoints

​Sessions

​Checkpoints

​Continue With

List Sessions

Attach Sessions

Stop Sessions

Capture Sessions and Their Checkpoints

Storage Backends

Inspect Checkpoints

Sessions

Checkpoints

Continue With