Common issues

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

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.

Confirm who you're signed in as

mergeguide auth whoami

Re-authenticate

mergeguide login --api-key mg_xxxxxxxxxxxxxxxx

Get an API key from portal.mergeguide.ai. In CI, pass the key from a secret rather than logging in interactively.

Run locally if you only need a local check

mergeguide check src/ --local

--local runs the check without submitting results to the dashboard.

Symptom: commits or pushes complete without a MergeGuide check.

Check hook status

mergeguide hooks status

Install (or reinstall) the hooks

mergeguide hooks install --hook-type pre-commit

Add --force to overwrite existing hooks. See Install git hooks.

Review bypasses

If a commit slipped through, check the bypass audit log:

mergeguide hooks bypasses

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.

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.

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

Disable the specific policy or exclude the path in config — see Reading findings.
While rolling out, run in advisory mode so findings report without blocking: mergeguide check . --advisory.