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

> Fix common checkpoint capture, linking, and sync issues.

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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](/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](/guides/repositories/github-app-access). For checkpoint push behavior, see [Checkpoint Storage](/guides/configuration/checkpoint-storage).
  </Accordion>

  <Accordion title="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/configuration/checkpoint-storage#checkpoint-remote) for setup details.
  </Accordion>

  <Accordion title="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](/guides/configuration/checkpoint-storage).
  </Accordion>

  <Accordion title="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}
    ```
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>