Skip to main content
Most BugViper issues fall into a small number of categories: misconfigured environment variables, a stopped service, or a mismatch between your GitHub App settings and your running infrastructure. Work through the relevant section below to diagnose and fix the problem.
If BugViper does not react at all when you comment on a PR, check the following in order:
  1. Is the GitHub App installed on this repository? Go to your GitHub App settings → Install App and confirm the app is installed on the account or organization that owns the repository. If you selected “Only select repositories” during installation, make sure this specific repo is in the list.
  2. Is the webhook URL correctly configured? In your GitHub App settings, open General and check the Webhook URL field. It must point to your running API service — for example, https://your-domain.com/api/v1/webhook or your current ngrok URL if you’re developing locally. An outdated or wrong URL means GitHub’s events are going nowhere.
  3. Is the API service running? Check that the BugViper API (port 8000) is up and healthy. If you’re using Docker Compose, run:
    Look for the API container in the list and confirm its status is Up. You can also hit the health endpoint directly:
If BugViper ran a review (you can confirm this in the dashboard) but did not post any inline comments to the PR, one of two things happened:
  • Findings were classified as nitpick — The verifier scored every finding below the NITPICK_CONFIDENCE_FLOOR threshold (default: 7 out of 10). Nitpick findings are intentionally held back from GitHub to reduce noise. Try lowering NITPICK_CONFIDENCE_FLOOR in your .env — for example, setting it to 5 will post more findings as inline comments.
  • Findings were classified as outside_diff — The verifier determined that the reported issues are in code that was not changed by the PR and suppressed them accordingly.
In both cases, you can view the full list of findings — including suppressed ones — in the Dashboard → Repos → [your repo] → [PR] → Run detail view.
This error means BugViper could not load your Firebase service account and initialize the Firebase Admin SDK.Check SERVICE_FILE_LOC — Open your .env file and confirm that SERVICE_FILE_LOC is set to the correct absolute path of your Firebase service account JSON file:
Common mistakes:
  • A relative path instead of an absolute path
  • A typo in the filename or directory
  • The file not existing at that path (for example, if you moved it after setting the variable)
  • Incorrect file permissions (the process running BugViper must be able to read the file)
You can verify the file is readable by running:
You should see the first few lines of a JSON object containing a "type": "service_account" field.
When developing locally, GitHub cannot reach your machine directly — you need a tunnel. BugViper uses ngrok for this.
  1. Confirm ngrok is running. Check that your ngrok process is active and forwarding to port 8000:
    If this returns an error or times out, restart ngrok:
  2. Check that your GitHub App webhook URL matches the ngrok URL. Go to your GitHub App settings → General → Webhook URL. The URL must be your current ngrok HTTPS URL followed by /api/v1/webhook, for example:
    If you restarted ngrok and got a new URL (because you’re not using a reserved domain), you need to update the GitHub App webhook URL to match.
  3. Use a reserved ngrok domain to avoid this problem altogether. Reserve a free static domain in the ngrok dashboard and always start ngrok with --domain=your-reserved-domain.ngrok-free.app. That way your webhook URL never changes between restarts.
A full AI review — especially in Deep mode on a large PR — can take several minutes. Here’s what to check if it seems stuck:
  • How large is the PR? A PR with 50+ changed files will naturally take longer than a small one. BugViper batches files and processes them sequentially (Normal mode) or in limited parallel groups (Deep mode).
  • Check DEEPAGENT_SANDBOX_TIMEOUT. The default is 1800 seconds (30 minutes). If your review is consistently timing out before finishing, increase this value in .env.
  • Check E2B sandbox status. Log in to the E2B dashboard and look at your active and recent sandboxes. If sandboxes are being created but immediately failing, there may be an issue with your E2B API key or plan limits.
  • Check MAX_CONCURRENT_SANDBOXES. If this is set too high relative to your E2B plan, sandbox creation may be throttled or queued, making reviews appear slow.
After installing the GitHub App on your GitHub account or organization, the BugViper dashboard needs to associate that installation with your logged-in user.
  1. Sign in to the BugViper dashboard at http://localhost:3000 (or your deployed frontend URL) using GitHub OAuth. If you are already signed in, sign out and back in — this refreshes the installation lookup.
  2. Confirm the installation is for the correct account. The GitHub App must be installed on the same GitHub account or organization that you used to sign in to the dashboard. If you installed it under a different account, you’ll need to sign in with that account or re-install the app under the correct one.
  3. Check NEXT_PUBLIC_GITHUB_APP_INSTALL_URL. If the install button in the dashboard is pointing to the wrong URL, the installation flow may not complete correctly. Verify this variable in your .env matches the Public link shown in your GitHub App settings.
If you see a Python ModuleNotFoundError when starting the API, review service, or ingestion service, your Python dependencies are out of sync with the project’s requirements. Run:
This installs all packages listed in pyproject.toml into the project’s virtual environment. You should run uv sync again any time you pull new changes from the repository, as new dependencies may have been added.If you’re running services inside Docker, rebuild the containers instead:
If you’re still stuck after working through the steps above, visit the Support page in the BugViper dashboard or reach out via the support form there. Include the relevant error message and which service (API, review, ingestion, or frontend) is producing it.