Troubleshooting

Common Issues

Audit-log shows N legacy mismatches

The Tamper-evidence chain panel may show a status like “INTACT (15 legacy)” with amber rows labeled “Legacy hash format (pre-fix row, not tampering).” This is expected and does not indicate any tampering or data integrity issue.

On April 30, 2026 we deployed an internal fix (PRI-157) that made audit-log row fingerprints fully deterministic against the database. Rows that were inserted before that deploy used the older, slightly non-deterministic hash form — so when we recompute their fingerprints today, the recompute will not match what was stored. Those rows will never re-verify, but they also cannot be tampered with silently because we still chain forward from their stored hashes. The chain remains an immutable audit trail.

Action: none required. Newer rows verify correctly. If the count of “legacy” rows ever increases, that is a bug worth reporting to support@mergewhy.com.

Linear ticket badges show as plain text instead of purple

If your DER detail page shows ticket keys (e.g. PRI-170) as plain gray badges instead of purple with a state suffix (PRI-170 — Done), the Linear integration is not connected or is connected with insufficient scope:

1. Go to Settings → Integrations → Linearand confirm the connection status is “Connected”.
2. Confirm the connected workspace contains the team prefix referenced in your PR titles. A token connected to a different workspace cannot read tickets from yours.
3. For PRs whose key does not exist in any Linear workspace (e.g. informal prefix in the title), this is expected; MergeWhy will silently skip the lookup and the badge stays plain.

Re-trigger enrichment by editing the PR description (any change works — even adding a trailing newline). The next webhook will re-run Jira, Linear, and Slack enrichment.

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