Handle failed pull requests

Understand why PRs fail in the merge queue and how to fix and resubmit them.

Understanding failures

When a PR fails in the merge queue, it’s automatically removed so it doesn’t block other PRs. Understanding why it failed helps you fix it quickly.

Why PRs fail in the queue

Legitimate test failures (most common):

• Tests fail because your code has a bug
• Tests fail due to conflicts with recently merged changes
• Tests fail because of missing or incorrect changes
• Integration tests reveal issues not caught locally

Flaky tests:

• Tests fail randomly, pass on retry
• Timing issues, race conditions, or external dependencies
• Network timeouts or resource contention
• See Anti-flake protection to handle these automatically

GitHub/CI infrastructure issues:

• GitHub API errors or rate limits
• CI runner out of resources or crashed
• Network connectivity problems
• Temporary infrastructure failures

Configuration problems:

• Branch protection rules misconfigured
• Required status checks not running
• Trunk unable to create test branches
• Missing CI configuration

Merge conflicts:

• Another PR merged and created conflicts
• Your branch needs to be rebased
• Files were moved or renamed

Manually restarting failed pull requests

The PR Details panel has a dropdown “Actions” menu, where you can:

1. Restart tests. Use this to manually restart testing of this PR.
2. Remove from queue. If the PR is “Queued”, then it will cancel it, preventing it from going into the queue until it is re-queued. If the PR is currently in the queue, it will be removed from the queue, which will restart all PRs that depended on it.

Trunk Merge Queue will automatically restart failed PRs when it can under certain conditions (see PR states). Since the restart is usually from a failed PR being removed from the queue, other PRs behind it will also be restarted. If you want to manually restart a PR, you can restart it in place by clicking the Details link in the Needs Resubmission tab to open the merge details screen. Then, click the Actions dropdown, and select Restart tests

There are a couple of reasons you might want to manually retry a PR. First, if a PR ends up in the PENDING_FAILURE state because of something transient like a CI runner disconnecting or flakey tests, you can retry the PR right away instead of waiting for PRs in front of it to pass or fail.

Another reason to restart a PR is if the proper tests don’t get kicked off due to a failure in the CI system. For example, if GitHub has an outage and is not triggering workflows or actions properly.

---

Failure reason reference

When Trunk drops a PR, it records a failure reason that appears in the Trunk Dashboard and in API responses. Use the tables below to understand what happened and how to recover.

Test and CI failures. These indicate that something went wrong during the test run itself.

Failure reason	What it means	What to do
TEST_RUN_REQUIRED_STATUS_FAILED	A required CI status check failed during the test run.	Check the CI logs for the failing check. Fix the underlying test or code issue and re-queue the PR.
TEST_RUN_TIMEOUT	The test run exceeded the configured timeout threshold.	Investigate why tests are running longer than expected. If the timeout is too short, adjust it in your Trunk configuration. Re-queue the PR once resolved.
TEST_RUN_FAILED_BY_OPTIMIZATION	Trunk’s optimization strategy (such as parallel testing or bisection) determined this PR caused a failure.	Check the test results to identify which tests failed. Fix the issue and re-queue the PR.

Configuration issues. These mean Trunk could not start a test run because of a problem with your configuration.

Failure reason	What it means	What to do
START_TEST_RUN_CONFIG_PARSING_FAILURE	Trunk could not parse your configuration file.	Check your .trunk/trunk.yaml for syntax errors. Fix the config and re-queue the PR.
START_TEST_RUN_CONFIG_BAD_VERSION	Your Trunk configuration file specifies an unsupported version.	Update the version field in .trunk/trunk.yaml to a supported value.
START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES	The required status checks in your configuration are invalid.	Review the required_statuses in your Trunk config and ensure they match actual CI job names.
START_TEST_RUN_NO_REQUIRED_STATUSES	No required status checks were found. Trunk needs at least one status check to validate a PR.	Add required status checks to your Trunk configuration or verify that your CI is reporting statuses correctly.

GitHub and infrastructure. These are usually transient issues with GitHub’s API.

Failure reason	What it means	What to do
GITHUB_API_MERGE_PR_FAILED	The GitHub API call to merge the PR failed. This is usually a transient GitHub issue.	Re-queue the PR. If the problem persists, check GitHub’s status page and verify your repository’s branch protection settings.
GITHUB_API_DIRECT_MERGE_PR_FAILED	The GitHub API call to directly merge (squash or rebase) the PR failed.	Re-queue the PR. If it persists, check GitHub’s status and your merge method settings in the repository.
GITHUB_API_RATE_LIMIT_EXCEEDED	Trunk hit GitHub’s API rate limit while processing this PR. This is a temporary condition.	Re-queue the PR. Trunk will retry normally once the rate limit window resets (typically within an hour). If this happens repeatedly, contact [e-mail].

PR state and timing. These occur when the PR’s state changed in a way that prevents Trunk from proceeding.

Failure reason	What it means	What to do
START_TEST_RUN_MERGE_CONFLICT	The PR has merge conflicts that prevent Trunk from creating a test branch.	Rebase or merge the target branch into your PR to resolve conflicts, then re-queue.
START_TEST_RUN_RETRY_EXHAUSTED	Trunk retried starting the test run multiple times and all attempts failed.	Check for persistent infrastructure issues or configuration problems. Fix the underlying cause and re-queue.
START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED	Draft PRs are not permitted to enter the merge queue.	Mark the PR as ready for review, then re-queue it.
PR_UPDATED_AT_MERGE_TIME	The PR was updated (new commits pushed) while Trunk was attempting to merge it.	Re-queue the PR. Trunk needs a stable PR to merge safely.

---

Needs Resubmission

A table of the PRs that failed testing and were removed from the queue. Address the failures, then resubmit them to rejoin the merge queue.

Retry failed pull requests from the Needs Resubmission tab

When a PR has been dropped from the queue, you can manually retry the PR by clicking the Details link in the Needs Resubmission tab to open the merge details screen. Then, click the Actions dropdown, and select Retry