Skip to main content
This page covers the most frequent errors users encounter when setting up or running BugViper, along with their causes and step-by-step fixes. If you’re seeing a problem not listed here, check Recent Deliveries in your GitHub App settings and the BugViper API logs for more detail.

​
”Repository not indexed” comment on a PR

Symptom: After posting @bugviper review on a pull request, BugViper replies with a message saying the repository is not indexed and asking you to ingest it first. Cause: BugViper checks whether the repository exists in your Neo4j graph before starting a review. If it doesn’t find a matching Repository node, it refuses to proceed. Fix: Ingest the repository before triggering a review. You can do this from the BugViper dashboard or via the API: 
curl -X POST https://your-bugviper-domain.com/api/v1/ingest/github \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner": "your-org", "repo_name": "your-repo"}'
Wait for the ingestion job to reach completed status, then post @bugviper review again.

​
Ingestion job stuck in “pending” or “running”

Symptom: You triggered ingestion and the job ID shows a pending or running status indefinitely — it never reaches completed or failed. Cause: The worker process that executes ingestion jobs may have crashed or been restarted after the job was dispatched. BugViper automatically marks jobs that have been in pending or dispatched state for more than 10 minutes as stale. Fix: Re-trigger the ingestion request. BugViper detects the stale job and allows a new one to be created for the same repository. If jobs continue to stall, check the BugViper API logs for error output and verify Neo4j is reachable using the connection URI in your environment configuration.

​
”Firebase not initialized” error

Symptom: BugViper fails to start or logs an error like Firebase not initialized or Could not deserialize key data. Cause: The SERVICE_FILE_LOC environment variable points to a file that doesn’t exist, can’t be read by the process, or contains invalid JSON. Fix:
1

Verify the file exists

ls -la "$(grep SERVICE_FILE_LOC .env | cut -d= -f2)"
If the file is missing, proceed to the next step.
2

Regenerate the service account key

  1. Open the Firebase Console
  2. Navigate to Project Settings → Service Accounts
  3. Click Generate new private key and download the JSON file
  4. Move the file to a secure location outside your repository
3

Update SERVICE_FILE_LOC

Set the path in your .env to the absolute path of the downloaded file:
SERVICE_FILE_LOC=/secrets/firebase-service-account.json
Never commit your service account JSON file to version control. Add the file to .gitignore and store it outside your repository directory.

​
”Neo4j connection refused”

Symptom: BugViper fails to start or API calls return errors mentioning Neo4j connection failure, ServiceUnavailable, or Connection refused. Cause: Neo4j is not running, the NEO4J_URI points to the wrong host or port, or the credentials are incorrect. Fix:
1

Check that Neo4j is running

docker ps | grep neo4j
If no container is listed, start Neo4j:
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5
2

Verify your NEO4J_URI

For a local Docker instance, the URI should be:
NEO4J_URI=bolt://localhost:7687
For Neo4j AuraDB, use the full neo4j+s:// connection string from your Aura dashboard. Make sure you’re not mixing up the HTTP browser port (7474) with the Bolt protocol port (7687).
3

Test the connection manually

Open your browser and go to http://localhost:7474. Log in with your Neo4j credentials. If the browser interface loads, Neo4j is running and accepting connections.

​
GitHub webhook not received

Symptom: You push code or post a @bugviper review comment but BugViper takes no action and there is no entry in your GitHub App’s Recent Deliveries list, or deliveries show a non-2xx response. Cause: The webhook URL in your GitHub App settings doesn’t match your running server. In local development, ngrok may not be running or the domain may have changed. Fix:
1

Check Recent Deliveries in GitHub

Go to your GitHub App settings → Advanced → Recent Deliveries. If a delivery appears with a 5xx or connection error, your server is reachable but returning an error. If no delivery appears at all, GitHub cannot reach your server.
2

Verify the webhook URL

In your GitHub App’s General settings, confirm the webhook URL is set to:
https://your-bugviper-domain.com/api/v1/webhook/onComment
For local development, this should be your ngrok URL (e.g., https://your-name.ngrok-free.app/api/v1/webhook/onComment).
3

Confirm ngrok is running (local dev)

curl https://your-reserved-domain.ngrok-free.app/health
If this times out, ngrok is not running. Restart it:
ngrok http 8000 --domain=your-reserved-domain.ngrok-free.app
4

Redeliver a failed webhook

In Recent Deliveries, click any failed delivery and use the Redeliver button to resend the payload without re-triggering the original event. This is useful for debugging without having to push code or post a new comment.

​
”Unrecognized command” response from @bugviper

Symptom: You mentioned @bugviper on a PR and BugViper replied with a message saying it doesn’t recognize the command and listing the valid options. Cause: The comment body contains @bugviper but the text after it doesn’t exactly match review or full review. Common triggers include typos, extra punctuation, or the command appearing inside quoted text. Fix: Post a new comment containing exactly one of the two supported commands: 
@bugviper review

@bugviper full review
The match is case-sensitive and must appear as plain text in the comment body, not inside a code block or quoted reply.

​
Semantic search returns no results

Symptom: You run a semantic (vector) search query from the BugViper dashboard or API and receive an empty results list, even for queries that should match code in the repository. Cause: Embeddings were not generated during ingestion. The graph contains the code nodes, but they have no vector property, so the similarity search has nothing to match against. Fix: Generate embeddings for the already-indexed repository without re-running full ingestion: 
curl -X POST https://your-bugviper-domain.com/api/v1/ingest/your-org/your-repo/embed \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"
Replace {owner} and {repo_name} with your repository’s owner and name. Embedding generation runs in the background and can take a few minutes for large repositories.
Embeddings use the openai/text-embedding-3-small model via OpenRouter and generate 1,536-dimensional vectors stored in Neo4j vector indexes. Make sure your OPENROUTER_API_KEY has sufficient credits before triggering embedding generation.

​
Review already running

Symptom: You post @bugviper review on a PR and BugViper replies that a review is already in progress and asks you to wait. Cause: BugViper tracks review state in Firestore. If a review was triggered recently and is still in the RUNNING state, BugViper blocks new review requests on the same PR to prevent duplicate comment floods. Fix: Wait for the current review to complete. BugViper posts a top-level summary comment to the PR when the review finishes. If no comment appears after 10 minutes, re-trigger the review by posting @bugviper review again — the previous job will have timed out by then and a new one can start.