Troubleshooting - Entire

Use this page when a checkpoint was not created, did not link to a commit, or did not appear where you expected.

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.

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 from the entire/checkpoints/v1 branch after it has been pushed.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
4. 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 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:

{
  "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 the entire/checkpoints/v1 branch.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 Checkpoint Storage.

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}

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.