> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mergeguide.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common issues

> Diagnose and fix the most common MergeGuide setup and run problems.

When something isn't working, start with `doctor` — it checks your configuration
and connectivity and reports what needs attention:

```bash theme={null}
mergeguide doctor
```

The sections below cover the most common problems by symptom.

## Authentication fails or `check` can't reach the dashboard

**Symptom:** commands report an authentication or connectivity error.

<Steps>
  <Step title="Confirm who you're signed in as">
    ```bash theme={null}
    mergeguide auth whoami
    ```
  </Step>

  <Step title="Re-authenticate">
    ```bash theme={null}
    mergeguide login --api-key mg_xxxxxxxxxxxxxxxx
    ```

    Get an API key from [portal.mergeguide.com](https://portal.mergeguide.com). In CI,
    pass the key from a secret rather than logging in interactively.
  </Step>

  <Step title="Run locally if you only need a local check">
    ```bash theme={null}
    mergeguide check src/ --local
    ```

    `--local` runs the check without submitting results to the dashboard.
  </Step>
</Steps>

## Git hooks aren't firing

**Symptom:** commits or pushes complete without a MergeGuide check.

<Steps>
  <Step title="Check hook status">
    ```bash theme={null}
    mergeguide hooks status
    ```
  </Step>

  <Step title="Install (or reinstall) the hooks">
    ```bash theme={null}
    mergeguide hooks install --hook-type pre-commit
    ```

    Add `--force` to overwrite existing hooks. See [Install git hooks](/install/git-hooks).
  </Step>

  <Step title="Review bypasses">
    If a commit slipped through, check the bypass audit log:

    ```bash theme={null}
    mergeguide hooks bypasses
    ```
  </Step>
</Steps>

## A check is slow or Semgrep times out

**Symptom:** `check` takes a long time or reports a Semgrep timeout.

* Raise the timeout: `mergeguide check src/ --semgrep-timeout 600`.
* Or run a faster pass with Semgrep disabled: `mergeguide check src/ --no-semgrep`.
* Narrow the scope by checking specific paths instead of the whole repo.

## An integration isn't reporting on pull requests

**Symptom:** PRs open but MergeGuide doesn't post a result.

* Confirm the repository is connected in the dashboard under **Repositories**.
* For webhook-based integrations (Bitbucket, Azure DevOps), confirm the webhook or
  service hook is configured with the correct URL and secret. See the integration
  page for your provider under [Integrations](/integrations/github).

## A check is failing the build on findings you've accepted

**Symptom:** CI fails on a finding you've reviewed and accepted.

* Disable the specific policy or exclude the path in config — see
  [Reading findings](/operation/reading-findings#suppress-a-finding).
* While rolling out, run in advisory mode so findings report without blocking:
  `mergeguide check . --advisory`.

## Next steps

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/troubleshooting/faq">
    Short answers to common questions.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command and flag.
  </Card>
</CardGroup>