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

# Troubleshooting

> Fix common BattleTest problems — missing PR review comments, stuck GitHub status checks, repositories not appearing, scans stuck Running, lost notifications.

## BattleTest PR review comment not appearing on GitHub pull request

<Accordion title="1. Check the GitHub App installation">
  Go to [Dashboard → Repositories](https://battletest.dev/dashboard). If the repository is missing or shows as disconnected, reinstall the GitHub App. See [how to connect a GitHub repository](/docs/how-to/connect-github).
</Accordion>

<Accordion title="2. Check webhook delivery in GitHub">
  In your repository: **Settings → GitHub Apps → BattleTest Security → Recent Deliveries**. Look for a `pull_request` event. If it shows a red ✗, expand it to see the error response.

  Common causes:

  * **Non-2xx response:** A temporary infrastructure issue. Use the **Redeliver** button to retry.
  * **No delivery shown:** The PR may have been opened on a branch not covered by your branch filter. Check Settings → PR Review → Branch filters.
</Accordion>

<Accordion title="3. Check your plan rate limit">
  If your account hit the hourly review limit when the PR was opened, the review was queued or routed to fallback depending on your overflow setting. The review will appear once capacity recovers, or switch to **Fallback** mode in Settings → PR Review for immediate (partial) coverage.
</Accordion>

## battletest/security-review status check stuck on "pending" in GitHub

The status check shows as pending either because the review is still running (expected for 2–4 minutes after the PR event) or because the webhook delivery failed before BattleTest received the event.

Check **Settings → GitHub Apps → BattleTest Security → Recent Deliveries** in your repository. If no `pull_request` delivery is listed for the PR that's stuck, the webhook didn't fire — re-trigger it by pushing any new commit to the PR branch or closing and reopening the PR.

## GitHub App installed but no repositories appear in BattleTest

After installation, check the GitHub App configuration page: **Settings → GitHub Apps → BattleTest Security → Configure**. Under Repository access, confirm at least one repository is selected. The default GitHub App flow sometimes leaves the selection empty — this is a GitHub UI issue on initial install.

## Live battletest scan failed or is stuck in "Running" for more than 30 minutes

<Accordion title="Domain not reachable from the internet">
  BattleTest scans from cloud infrastructure. The target must be accessible from the public internet — VPN-only, localhost, and internal-only targets are not supported.

  Test from your terminal:

  ```bash theme={null}
  curl -I https://your-domain.com
  ```

  If this returns a connection error, the scanner will also fail. The domain must respond to HTTP requests from outside your network.
</Accordion>

<Accordion title="SSL certificate error on the target domain">
  An invalid, self-signed, or expired SSL certificate causes the crawler to fail immediately. Resolve the certificate issue first, then retry the scan. For staging environments that intentionally use self-signed certificates, contact [wale@battletest.dev](mailto:wale@battletest.dev) — there is a workaround available.
</Accordion>

<Accordion title="Scan stuck in Running for over 30 minutes">
  Cancel the scan from the run detail page (**Actions → Cancel**). Start a fresh scan. If the issue repeats, contact support with the scan run ID from the URL — it looks like `scan_abc123` in the dashboard URL.
</Accordion>

## Secret was committed to git and BattleTest flagged it — what do I do?

See [How to respond to an exposed credential](/docs/how-to/exposed-secrets) for a step-by-step guide: rotating the credential, removing it from current code, purging it from git history, and preventing recurrence.

## BattleTest not scanning pull requests on feature branches

By default, BattleTest only reviews PRs targeting your default branch. To scan all branches:

1. Go to **Settings → PR Review → Branch filters**
2. Switch from your default branch to **All branches**
3. Save

You'll also need to add GitHub branch protection rules on those branches if you want the status check to be required.

## I'm not receiving BattleTest email notifications

Check [Settings → Notifications](https://battletest.dev/settings?tab=notifications) and confirm email is enabled. Check your spam folder — the first email from `noreply@battletest.dev` is sometimes filtered. Add the address to your contacts to prevent future filtering.

## GitHub App was uninstalled accidentally

Reinstall it from **Dashboard → Repositories → Connect GitHub**. Your findings history and settings are preserved — nothing is deleted on uninstall, only the GitHub access is revoked.

## Still stuck?

Email [wale@battletest.dev](mailto:wale@battletest.dev) with your repository name or scan run ID. We'll investigate directly and respond within one business day.