Troubleshooting

Common Issues

GitHub webhooks not arriving

If DERs are not being created from pull requests, check the following:

1. Verify the GitHub App is installed on the correct repositories. Go to GitHub Settings → Applications → MergeWhy and check repository access.
2. Check webhook delivery logs at GitHub App Settings → Advanced → Recent Deliveries. Look for failed deliveries (non-200 status codes).
3. Verify GITHUB_WEBHOOK_SECRET matches between your environment and the GitHub App configuration.

Database connection errors

If you see “connection refused” or “timeout” errors:

• Ensure DATABASE_URL uses the pooled connection string (with connection pool parameters)
• Check that PostgreSQL is accessible from the application container (network/firewall rules)
• For self-hosted, verify the postgres service is healthy in Docker Compose

OIDC authentication failures

• Verify the redirect URI in your IdP exactly matches {NEXT_PUBLIC_APP_URL}/api/auth/callback/oidc
• Check that NEXTAUTH_SECRET is set (required for session encryption)
• Ensure the OIDC issuer URL resolves to a valid .well-known/openid-configuration endpoint

AI analysis not running

AI-powered analysis requires an LLM provider API key. If none is configured, MergeWhy falls back to rule-based analysis which checks:

• Description length and keyword presence
• Ticket reference patterns
• Review and approval counts

To enable AI analysis, set ANTHROPIC_API_KEY, OPENAI_API_KEY, or configure Ollama for local inference.

Error Codes

Getting Help

If you encounter an issue not covered here, reach out through one of these channels:

• Email: support@mergewhy.com
• GitHub Issues: github.com/mergewhy/mergewhy/issues
• Enterprise Support: Contact your account manager for priority assistance