> ## 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 repository mirror setup, access, clone, fetch, and push issues.

Use this page when a repository mirror cannot be created, cloned, fetched, pushed to, or accessed by the expected users.

## `git-remote-entire` Diagnostics

Git invokes `git-remote-entire` when a remote uses an `entire://` URL. Confirm that the helper is installed and available on `PATH`:

```bash theme={null}
git-remote-entire --version
```

If the shell cannot find the command, [update or reinstall Entire](/installation#install-and-update-entire). The release archive installs `entire` and `git-remote-entire` together.

For a clone or fetch failure, confirm your login and the placement before testing the remote directly:

```bash theme={null}
entire auth status
entire repo view /gh/OWNER/REPO
git ls-remote entire://CLUSTER_HOST/gh/OWNER/REPO
```

The URL must include the cluster host. Use `entire repo view /gh/OWNER/REPO` to find the full URL for each cluster, or use `entire repo clone /gh/OWNER/REPO` to let Entire select a placement.

Set `ENTIRE_DEBUG` to include authentication, cluster discovery, request, response, and timing details from the helper on standard error:

```bash theme={null}
ENTIRE_DEBUG=1 git ls-remote entire://CLUSTER_HOST/gh/OWNER/REPO
```

Review diagnostic output before sharing it outside your organization.

<AccordionGroup>
  <Accordion title="Unknown Command &#x22;repo&#x22;">
    Your `entire` binary may be older than the repository mirror commands.

    [Update Entire](/installation#install-and-update-entire), then try again:

    ```bash theme={null}
    entire repo mirror add /gh/OWNER/REPO
    ```
  </Accordion>

  <Accordion title="The Repository Is Missing from GitHub App Access">
    Confirm that the Entire GitHub App is installed and allowed to access the repository.

    1. Open [GitHub installed apps](https://github.com/settings/installations).
    2. Find **Entire**.
    3. Click **Configure**.
    4. Choose **All repositories** or select the repository you want to mirror.
    5. Save the GitHub App configuration.

    For the full GitHub App setup flow, see [GitHub App Access](/guides/repositories/github-app-access).
  </Accordion>

  <Accordion title="A User Cannot Create or Join a Mirror">
    Check both access requirements:

    * The Entire GitHub App can access the repository.
    * The user has access to the repository in GitHub.
    * The user has signed in with the Entire CLI using `entire login`.

    After those are true, the user can create or join the mirror:

    ```bash theme={null}
    entire repo mirror add /gh/OWNER/REPO
    ```

    Entire syncs GitHub collaborators into mirror access hourly. If the user recently got GitHub access or recently signed in to Entire, wait for the next sync or have them run `entire repo mirror add /gh/OWNER/REPO`.

    See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions) for GitHub-synced access, hourly collaborator sync, and self-onboarding.
  </Accordion>

  <Accordion title="Mirror Creation Takes a While">
    By default `entire repo mirror add` waits for the initial GitHub-to-Entire clone to finish. Large repositories can take longer.

    If you only need to register the mirror and check back later, use `--no-wait`:

    ```bash theme={null}
    entire repo mirror add /gh/OWNER/REPO --no-wait
    ```
  </Accordion>

  <Accordion title="Git Cannot Clone or Fetch from the Mirror">
    Confirm that the repository has a ready placement and let Entire select its clone URL:

    ```bash theme={null}
    entire repo view /gh/OWNER/REPO
    entire repo clone /gh/OWNER/REPO
    ```

    If the repository has placements on several clusters, select one explicitly:

    ```bash theme={null}
    entire repo clone /gh/OWNER/REPO --cluster CLUSTER_HOST
    ```

    If cloning still fails:

    * Run `entire login` to refresh your Entire session.
    * Confirm you have GitHub collaborator access to the repository.
    * If your GitHub access changed recently, wait for the next hourly collaborator sync.
    * Confirm your network can reach the selected cluster host.
    * If you added the mirror to an existing checkout, run `git remote -v` and confirm the remote URL.
    * Run the [`git-remote-entire` diagnostics](#git-remote-entire-diagnostics).
  </Accordion>

  <Accordion title="Cloning a Mirror with LFS Files Fails During Checkout">
    Mirrors do not currently support Git LFS. When you clone a mirror of a repository that uses LFS, the clone succeeds but checkout fails with a smudge error like:

    ```text theme={null}
    Error downloading object: ... batch request: ssh: Could not resolve hostname entire
    error: external filter 'git-lfs filter-process' failed
    fatal: <file>: smudge filter lfs failed
    ```

    As a workaround, point Git LFS at GitHub so that large file transfers go through GitHub, while regular Git operations keep using the mirror:

    ```bash theme={null}
    git config lfs.url "https://github.com/<owner>/<repo>.git/info/lfs"
    ```

    See [Git LFS](/guides/repositories/mirrors#git-lfs) for the full workaround, including how to recover a fresh clone that failed at checkout.
  </Accordion>

  <Accordion title="Pushes Through the Mirror Are Rejected">
    Pushes through a mirror are still authenticated with GitHub.

    If a push is rejected:

    * Confirm the user has write access to the GitHub repository.
    * Confirm branch protection rules and required checks allow the push.
    * Confirm the Entire GitHub App can access the repository.
    * Refresh the user's Entire login.

    ```bash theme={null}
    entire login
    ```

    Do not use `entire logout` to refresh: it drops every saved login and ends your CLI sessions on other machines too.
  </Accordion>

  <Accordion title="A Pushed Branch Does Not Appear on GitHub">
    Branch names that start with `entire/unmirrored/` are intentionally never synced to GitHub. The branch exists only in the Entire region you pushed it to.

    To publish the work on GitHub, push the commits to a branch name outside the prefix:

    ```bash theme={null}
    git push entire "entire/unmirrored/<branch>:<branch>"
    ```

    See [Entire-Native Branches](/guides/repositories/entire-native-branches) for how unmirrored branches work.
  </Accordion>

  <Accordion title="A Removed User Can Still Read from a Mirror">
    Removing GitHub access prevents push-through writes because pushes are authenticated with GitHub. Clone and fetch access may continue until the next hourly collaborator sync.

    See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions#offboard-a-user) for the offboarding flow.
  </Accordion>

  <Accordion title="The Mirror Was Removed but a Local Checkout Still Points to It">
    Removing a server-side mirror placement does not edit local Git configuration.

    Check the remote in the local checkout:

    ```bash theme={null}
    git remote -v
    ```

    To switch back to GitHub:

    ```bash theme={null}
    git remote set-url origin git@github.com:<owner>/<repo>.git
    ```

    Entire no longer saves the previous URL under `upstream`. If you repointed `origin` with `entire repo remote add origin --override`, the replaced URL was printed once and not stored.
  </Accordion>

  <Accordion title="Still Stuck?">
    Include these details when asking for help:

    * `entire version`
    * the GitHub repository URL
    * the `entire://` mirror URL
    * whether the Entire GitHub App can access the repository
    * whether the issue happens during create, clone, fetch, or push
    * the full error message

    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>

## Continue With

<CardGroup cols={2}>
  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Learn how mirrors make GitHub repositories available in Entire.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>
</CardGroup>