Skip to main content

​
Webhook not receiving events

The webhook URL configured on your GitHub App must exactly match the API Gateway endpoint printed during npx mergewatch@latest init.Fix: Go to GitHub Settings > Developer settings > GitHub Apps > your app > Webhook URL and verify it matches your API Gateway URL (e.g. https://abc123.execute-api.us-east-1.amazonaws.com/prod).
The HMAC secret stored in SSM must match the secret configured on the GitHub App. A mismatch causes every delivery to fail signature validation.Fix: Verify the SSM parameter value matches your GitHub App’s webhook secret:
aws ssm get-parameter \
  --name "/mergewatch/{stage}/github-webhook-secret" \
  --with-decryption \
  --query "Parameter.Value" \
  --output text
Compare this with the value in GitHub App settings > Webhook > Secret.
Events may be arriving at API Gateway but failing inside the WebhookHandler Lambda.Fix: Check the Lambda logs:
npx mergewatch@latest logs
Look for signature validation errors, missing environment variables, or SQS publish failures in the CloudWatch output.

​
Review not posting comments

The GitHub App needs write access to pull requests to post review comments.Fix: Go to GitHub App settings > Permissions & events > Repository permissions and confirm Pull requests is set to Read & write.
Amazon Bedrock requires you to explicitly enable model access before invoking a model.Fix: Open the AWS Console > Amazon Bedrock > Model access and enable the Claude model your deployment uses. This must be done in the same region as your deployment.
The ReviewAgent Lambda’s execution role must include the bedrock:InvokeModel permission.Fix: Check the Lambda’s execution role in the AWS Console and verify it has a policy allowing bedrock:InvokeModel on the model ARN. If you deployed with SAM, redeploy — the template includes this permission by default.
Fix: Check the ReviewAgent Lambda logs directly:
npm run logs:agent
Look for Bedrock API errors, permission denied responses, or timeout exceptions.

​
”Skipped” on every PR

The ignore_patterns configuration may be matching all files in the diff.Fix: Review your .mergewatch.yml file:
# Example — this skips everything under docs/ and all lock files
rules:
  ignore_patterns:
    - "docs/**"
    - "*.lock"
Narrow the patterns or remove entries that are too aggressive.
Draft pull requests are skipped by default.Fix: Either mark the PR as Ready for review or set skip_drafts: false in your .mergewatch.yml:
rules:
  skip_drafts: false
MergeWatch auto-skips a PR when every changed file matches an excluded pattern (lock files, generated code, documentation, etc.).Fix: Confirm the PR includes at least one source file that is not in an excluded path. Check the skip reason in the review record or Lambda logs.

​
Health check failing

The health endpoint tells you which secret is missing. A missing SSM parameter typically means the install wizard was interrupted.Fix: Run the health check and read the output:
npx mergewatch@latest health
Re-run npx mergewatch@latest init to recreate missing parameters, or manually add them:
aws ssm put-parameter \
  --name "/mergewatch/{stage}/github-webhook-secret" \
  --type SecureString \
  --value "your-secret-value"
All SSM parameters must follow the naming convention /mergewatch/{stage}/*. A different prefix causes lookups to fail.Fix: List your SSM parameters and verify the path:
aws ssm get-parameters-by-path \
  --path "/mergewatch/prod/" \
  --query "Parameters[].Name" \
  --output table
The stage in the SSM path must match the stage used during deployment.

​
Dashboard 401 / auth failing

The dashboard uses NextAuth for session management. A missing NEXTAUTH_SECRET causes all authentication to fail with a 401.Fix: Set the environment variable on your dashboard deployment:
# Generate a random secret
openssl rand -base64 32
Add the output as NEXTAUTH_SECRET in your environment configuration.
The callback URL configured on the GitHub OAuth App must match the dashboard’s URL exactly.Fix: Go to GitHub Settings > Developer settings > OAuth Apps > your app and set the Authorization callback URL to:
https://your-dashboard-url.com/api/auth/callback/github
NextAuth needs the NEXTAUTH_URL variable to construct callback URLs. If it is missing or wrong, redirects break.Fix: Set NEXTAUTH_URL to the canonical URL of your dashboard (e.g. https://dashboard.mergewatch.dev). Do not include a trailing slash.

​
SAM deploy failing

A stack rollback means one or more resources failed to create or update.Fix: Inspect the stack events to find the root cause:
aws cloudformation describe-stack-events \
  --stack-name mergewatch-prod \
  --query "StackEvents[?ResourceStatus=='CREATE_FAILED'].[LogicalResourceId,ResourceStatusReason]" \
  --output table
The IAM identity running sam deploy needs broad permissions to create the stack resources.Fix: Ensure the deploy role or user has at minimum:
  • cloudformation:*
  • lambda:*
  • apigateway:*
  • dynamodb:*
  • sqs:*
  • iam:PassRole
For production, scope these permissions down to the specific resource ARNs after the initial deployment succeeds.
MergeWatch requires Node.js 20 or later. SAM build fails if the local runtime is older.Fix: Check your version and upgrade if needed:
node --version
# Must be v20.x or later

​
Bedrock throttling

Bedrock applies per-model, per-region request quotas. High review volume can hit these limits.Fix: Request a quota increase in the AWS Console > Service Quotas > Amazon Bedrock.
Cross-region inference profiles distribute requests across multiple regions, increasing effective throughput.Fix: Set the model to a cross-region inference profile in your configuration:
# .mergewatch.yml
model: us.anthropic.claude-sonnet-4-20250514-v1:0
The us. prefix enables cross-region inference across US regions. This is the recommended setting for production deployments.

​
Review taking too long (>5 minutes)

PRs with more than 50 changed files take significantly longer to review.Fix: Set a file limit in your .mergewatch.yml:
rules:
  max_files: 50
Files beyond the limit are summarized rather than reviewed line-by-line.
The first invocation after a period of inactivity incurs a cold start (5-10 seconds extra).Fix: This is expected behavior. Subsequent invocations within the same warm period are faster. For consistently low latency, enable Lambda provisioned concurrency on the ReviewAgent function.
Some Bedrock regions experience higher latency during peak hours.Fix: Check the Bedrock region’s CloudWatch metrics for InvocationLatency. Consider switching to a region with lower latency or enabling cross-region inference.