## 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](https://docs.entire.io/guides/sessions/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](https://docs.entire.io/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:

```
entire session attach SESSION_ID -a AGENT
```

See [Attach Sessions](https://docs.entire.io/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](https://docs.entire.io/guides/sessions/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](https://docs.entire.io/guides/configuration/checkpoint-storage#configure-checkpoint-storage)
4. Confirm the Entire GitHub App can access the repository

For GitHub App access issues, see [Install the Entire GitHub App](https://docs.entire.io/guides/repositories/github-app-access). For checkpoint push behavior, see [Checkpoint Storage](https://docs.entire.io/guides/configuration/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](https://docs.entire.io/guides/configuration/checkpoint-storage#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](https://docs.entire.io/guides/configuration/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](https://github.com/entireio/cli) or ask in the [Entire Discord](https://discord.gg/jZJs3Tue4S).